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1 ime is money. 


The advantages of OS/2® are elear. “At Life Care 
Development Corp., we create applications for sale 
to physicians, psychiatrists and drug counselors for 
tracking patient and insurance information, and 
medicine and treatment goals. We make use of 
OS/2 s inherent development capabilities like the 
REXX language as well as WorkFrame/2 (IBM’s 
development environment), C Set/2 compiler and 
Borland ObjectVision? For us, OS/2 has meant 
heightened productivity, shortened development 
time and improved quality of product.” 

Work in a customizable object-oriented 
environment without constraints. Enjoy true pre¬ 
emptive multitasking, unlike what 
you get with Windows™ and other 
DOS extenders. “With OS/2,1 can 
reliably run several development 
applications at the same time: 


ObjectVision 
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edit in one window, compile in 
another, link in a third and test 
in a fourth. I’m amazed how quickly 
I can compile a program while print¬ 
ing a copy of the source code.” OS/2 
gives you the capability to have mul¬ 
tiple conligurable sessions in which 
to build and test your applications. 

OS/2 is easier to get into. 

OS/2 Crash Protection™ helps you lose your 
fear of crashing and rebooting. If one app goes 
down due to a bug, the rest you’re working on 
won’t. OS/2 isolates the failure, 
letting you fix it and restart it with¬ 
out affecting other apps. Dynamic 
Link Libraries allow applications 
to share common functions, 
making them smaller and easier 
to maintain. 
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-WINNER- 
PC Magazine Award 
for Technical Excellence 
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OPERATING SYSTEMS AND 
SOFTWARE STANDARDS 

OS/2, Version 2.0 
IBM Corporation 


I’ll never go back.” 

“I may be a small ISV, but IBM has always 
treated me like a big fish." I BM’s valuable technical 
service and marketing support includes OS/2 Sup¬ 
port Line, IBMLink, the IBM OS/2 bulletin board 
system and several OS/2 developer forums on 
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heq • tllnCreateMsgQueue(hab. 0L): 


DosBeep(BEEP_MARN_FREQ. BEEP_MAPH_DUR) 
WlnTeralnata(hab): 
return(R£TURN_ERROR); 


lf(llnlt()) 


NMSage6ox( HHND.DESKTOP. 

IDMSG_INITFAILED. 



Line 1B5 of 1665 Column 1 3 File- 


/« 

WlnCalcF raeeRect (hwixl. (PfiECTl)iptr 
ptrack->cxGrid ■ Board.cx; 
ptrack->cyGrld * Board.cy; 
ptrack >fs |- TF.GRID; 

) /» end It */ 

) /■ endlf «/ 
return( (MRESULT)rc): 

) break: 


Return via the normal frai 
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In the Workplace Shell™ you can edit source code files while 
compiling and debugging in the background. 













































The no-comparison comparison chart. 



Windows 3.1 

OS/2 

Virtual memory limit 

4 x physical 

512MB (disk space) 

Memory model 

Segmented 

(64KB) 

Flat memory objects 

APIs 

16 bit 

Full 32 bit 

Multitasking—DOS apps 

Time slicing 

Pre-emptive time slicing 

Multitasking—Windows/PM apps 

Cooperative 

Pre-emptive 

Priority 

Static (set by user) 

Dynamic 

Dispatc liability 

Process 

Thread 

System services 

Serial 

Parallel 

Protection between apps 

Unprotected 

Protected 

Kernal protection— 

DOS/Win/PM apps 

Unprotected 

Protected 

File system 

FAT 

Enhanced FAT and 
installable file systems 
(HPFS, CD-ROM) 

User interface 

Windowed 

Object oriented 


IBM and OS/2 are registered trademarks and Workplace Shell and OS/2 Crash Protection 
are trademarks of International Business Machines Corporation. All other products are 
trademarks or registered trademarks of their respective companies. ©1993 IBM Corp. 



CompuServe? “If 1 run into a problem, the OS/2 
Developer Assistance Program is there to help.” 

The 32-bit operating system lets you break 
through the 64K code segment barrier and convert 
to a flat memory model with up to 512MB of mem¬ 
ory per session for writing code. “Writing is easier 
and faster than ever—and bugs have never been 
easier to uncover and zap.” 

“I’m actually having fun again.’’ 

But the best reason for leaving Windows 
and other DOS extenders is the opportunity to 
develop truly revolutionary OS/2 applications. You 
could say OS/2 has closed the door on Windows. 
For the free white paper on why OS/2 is the 
developer s platform 
of choice, or for more 
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Add Sophistication and Flexibility to 
Your Windows Application 


Professions! Visual Architect™ 

Toolbox For Windows For Visual Basic 


the Industry's 


With 23 custom controls - including the 
industry's only full-featured Spreadsheet 
control - and more than 300 functions, 
Professional ToolBox is the most complete, 
flexible and powerful Windows development 
package on the market. 


Visual Architect™ is a product that 
no Visual Basic developer should 
do without. Designed to accelerate 
your development schedule, Visual 
Architect™ can handle any 
application you're developing. 



The Spreadsheet control of ToolBox is 
unparalleled by any other package in its 
features, flexibility and power. 

New features include: 

• Full sorting support 

• Addition of a checkbox celltype and owner 
draw celltype 

• Place borders around a cell, row, column, 
or range of cells 

• Virtualized database support 

• Selection of multiple blocks 

• Overflow text to next column 

• Single-select, multi-select feature 

• Place multi-line edit within a cell 

• Change color of grid 

• Drag and drop 

• Plus, full clipboard support 

Other custom controls are Formatted Edit 
Controls, Tool Bar and Status Bar, 3D 
effects, View Pictures with animation, and 
Enhanced Listbox. Functions include DOS 
System functions, Date/Time support, String 
functions, and Enhanced File support. 

Professional ToolBox supports MSC 7.0, 
Borland C++, Borland C++ Owl, Turbo 
Pascal, Actor, WindowsMaker Pro, Borland 
Resource Workshop, GFA, Microsoft C++ 
and Dialog Editor. 

Price $345 (no royalties) 


The "true" Spreadsheet control, makes 
Visual Architect™ stand out from any other 
software package. A major design goal was 
to make the spreadsheet extremely flexible 
and powerful. It can be used within your 
application as a functional spreadsheet - as 
a simple way of obtaining variable lines of 
data from the user - or as an easy way of 
displaying tables of information from a 
database. 

Because of its extreme flexibility, the 
spreadsheet can be customized for each 
individual user. It can be optionally locked 
so the user can't make changes. The width 
and height of columns and rows may be 
changed. The font, color, and data type may 
be changed for any row, column or cell. 

Cells can have the following data types: 
edit, date, time, integer, float, static, 
formatted pic, combobox, button, and 
picture. Formulas can be added to any cell. 
Full-print support is built-in. 

Other features of Visual Architect™ include 
the Formatted PIC, Integer, Floating Point, 
Date with Calendar, Time and View Text. 

The Visual Architect™ manual is 
professionally written and 
contains extensive documentation 

Visual Architect™ 

Winner of Reader’s Choice Award 1992 
Only $245 (no royalties) 


Development Tools Backed by Professionals 

"FarPoint's Visual Architect™ spreadsheet is a 
proven and robust tool that can easily meet the 
changes of mission critical real world applications. 
FarPoint's design and documentation made it easy 
to master and embed the spreadsheet in our systems. 
Being Vertical Application Integrators, we demand 
versatility from all of our tools , and FarPoint's 
Visual Architect™ exceeded our expectations." 

GregMelnick 

Vice President Triple-I Software 

Triple-l has been providing consulting and technical service solutions to 
Fortune 500 companies for 21 years. 


FarPoint Technologies offers a 30 day, no-hassle, money back 

FarPoint Technologies, Inc., 585A Southlake Blvd., Southport Office Pi 
To order or receive additional information call: 1-800-645-5913 or 1-81 
Technical Support: 1-804-378-1011 Fax: 1-804-378-1015 

Agency: MF Schwab & Associates, Inc., Dublin, OH 
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From 

the Editor 


The long-promised dual-font edit control from Paul Bonneau appears this month. 
Remember, I warned you it would not be pretty. Actually, since he first wrote it, 
Paul has modularized the part of the code that intercepts calls to Windows func¬ 
tions. That makes it somewhat reusable for other programs. In fact, Paul's column 
will be calling on this code again in a future issue to solve another intractable reader 
problem. 

Speaking of hacks, take a look at the sidebar in Paula Tomlinson’s NT device 
driver article if you want to see a great one from Microsoft That’s the ever-present 
problem with building software. You can create a beautiful, pristine design (for an 
operating system, for example), but it’s all downhill from there, as backward com¬ 
patibility and changing requirements hammer you into compromise after com¬ 
promise. Nevertheless, there is something gruesomely appealing about the fact that I 
will probably be able to someday run my 16-bit, Intel DOS binaries on computer 
architectures that haven’t even been designed yet. I predict a new profession will 
emerge within my lifetime: software archaeology! 

I didn't do too well at predicting when Windows NT would ship, so let’s see if I 
can predict what's in next month’s issue. We’re starting a series of articles by Steven 
Palmer that I call Visual Implementation. These are basically short, focused articles 
that give you reusable code to implement specific user interface features. For ex¬ 
ample, the first article implements a most-recently-used file list for the File menu, if 
your only debugging tool is the symbolic debugger that came with your compiler, 
you’ll want to read about my experiences with some non-debugger debugging tools. 
If nothing else, you can laugh at all the bugs in my code that they uncovered. 
Finally, in counterbalance to this month’s device driver coverage, next month Karen 
Flazzah will demonstrate that, although it's a bit tricky, you can handle hardware 
interrupts in ring 0 with a DLL without having to write a VxD. 

My book of the month is Computer Architecture: A Quantitative Approach, by 
Hennessy and Patterson. I won't ever get to design a new computer (although I 
spent some time in college being instructed in that endeavor), but understanding the 
hardware has always given me an edge over programmers who don't. This “instant 
classic” was actually published a couple of years ago, but it's been sneaking onto my 
desktop more often lately. RISC architectures, advanced pipelining, and symmetric 
multiprocessing all seemed pretty academic to me a few years ago. Now, however, 
my next “PC" may very well have all of these features and I'm afraid the next time I 
reach down to do a little assembly language coding, I may not pull my hand back in 
one piece! If you need a readable, remedial hardware course to bring you into the 
90s, I highly recommend this book. Part of what makes it readable is that it is 
grounded in case studies of CPUs, including the familiar 80x86 architecture. 


Ron Burk 

Editor 

CIS: 70302,2566-, BIX: rlburk- Internet: ronb@rdpub.com (“... !uunet!rdpub!ronb") 
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Phases Has Everything You Need 

Lower CASE • Visual Development • integrated RDBMS • Help Generator 
Extensible C or Pascal Code • Report Writer • Interactive Data Browser 



From start to finish, Phase3 is the fastest way to develop a complex 
Windows application. Whether you are writing custom programs or 
developing packages for resale, there’s no quicker or easier way to the 
finish than Phase3. Phase3 is a comprehensive Windows application 
development system with an integrated, relationally complete database 
Phase3 generates high performance, extensible C or Pascal programs. 
And Phase3’s context sensitive help and substantial on-line documen¬ 
tation make you productive on Day 1. 

Get a Quick Start with Automated Design 

Phase3’s Lower CASE front end automates data model design with 
Entity-Relationship modeling. Database creation, including appropriate 
indexes, is automatic. And you are prompted to choose the appropriate 
data integrity mles to be automatically enforced at runtime. 

Move to the Head of the Pack with a Robust, Integrated RDBMS 

The power of a Phase3 application lies in the relationally complete database supplied as a 
DLL. Access the database with built-in API routines. Automatic database restructuring, 
built-in database integrity enforcement, rollback recovery and transaction control are but 
several of the features that make Phase3 a database thoroughbred. 

Boost Your Performance with Visual Development 

Phase3 gives you complete interactive control over screen design. Place push buttons, 
radio buttons, dialog boxes, all the standard Windows screen items with ease. Create 
data entry screens quickly with Phase3’s populate function. Select appropriate 
Windows API commands from pick lists or write your own code. 

Make Final Adjustments in the Stretch \ 

To win you need to adjust — to changing user demands, to competitor pres¬ 
sures. Phase3’s Hierarchy Chart is a visual tree of every screen, report, and 
code procedure in an application. It makes no difference whether it's been 
several minutes or several years since you developed an application. Point and 
click and you’ve instantly accessed the code segment you want to modify. 


Phase3™ is a trademark of Phase3 Software Pty. Ltd., Australia. 

All other product names referenced herein are trademarks of their respective companies. 



Gross the Finish with an Award 
Winning Application 

Context sensitive help is a hallmark of an 
award winning Windows application. 
Many developers stumble at the finish line 
because they’ve underestimated the effort 
required to create the help subsystem. 
Quickly create context sensitive help, 
including highlighted triggers that branch 
to related topics, with Phase3’s Help 
Generator. And cross the finish with core 
documentation automatically produced by 
Phase3’s database schema, Hierarchy 
Chart, and E-R Diagram. 


Call, Fax or Write to See How You 
Can Win with Phase3 

1 - 800 - 851-5650 

We’ll send you a complete information kit. 

^ Phase3 Software,Inc. 

Ventura, CA 
Phone: (805)641-9366 
Fax: (805) 641-9083 

In Australia; 

Phase3 Software Pty. Ltd. 
Canberrra ACT 
Phone: (06) 285-4155 
Fax: (06) 285-4169 


□ Request 102 on Reader Service Card □ 







Paula Tomlinson received an Electrical Engineering degree from Colorado State Univer¬ 
sity. For the past five years, she has been an engineer with Hewlett-Packard. Her 
engineering experiences include the development of Windows printer drivers, Win¬ 
dows 3.x VxDS, Windows NT VDDs, Windows NT DLLs, DOS Device Drivers, TSRs, and a 
variety of DOS and Windows-based commercial applications. The opinions expressed 
in this column are hers alone and do not necessarily reflect the opinions of 
Hewlett-Packard. Send questions or correspondence to Paula via internet as 
hpscanner@hpgrla.gr.hp.com. 


Windows NT Virtual Device 
Drivers for Hardware-Dependent 
16-Bit Applications 


Windows NT promises to run "most" 16-bit Windows and DOS applications 
without modification. In fact, Windows NT uses a sophisticated 80x86 emulator to 
run 16-bit Windows 3.1 and DOS executables, even on non-Intel platforms such as 
the DEC Alpha and the MIPS R4000. An important exception to this rule is 16-bit 
applications that directly access hardware other than such basic devices as the dis¬ 
play, parallel ports, serial ports, mouse, and the keyboard. While many developers 
are struggling with the decision of when to port their existing applications to 32-bits, 
my first order of business is supporting current 16-bit applications under Windows NT. 

As a developer of applications for the HP ScanJet family of scanners, my problem 
was further complicated by the fact that a large body of third-party 16-bit applica¬ 
tions is currently available for HP scanners. I wanted a solution that allowed all of 
these applications to run unmodified under Windows NT. I had one bit of good 
fortune in that our current family of scanners uses a SCSI interface and Windows NT 
provides a rich set of kernel-mode device drivers for the SCSI interface, in addition to 
parallel and serial interfaces. 


The Windows NT VDM and Device Drivers 

DOS and 16-bit Windows applications can run under Windows NT because of the 
emulation provided by the Windows NT Virtual DOS Machine (VDM) environment 
subsystem. The VDM is actually a multithreaded Win32 application that provides a 
complete virtual DOS machine environment. When the user starts a DOS or 16-bit 
Windows application, the Win32 subsystem detects the DOS executable, starts a 
VDM process, loads drivers from the config.nt file, loads the application into the 
VDM's virtual address space, and executes it. Each DOS application is placed in its 
own VDM process with a private virtual address space containing DOS emulation 
code and any DOS device drivers that were loaded. For 16-bit Windows applications, 
the VDM loads the WOW (Windows on Win32) environment, essentially a multi¬ 
threaded VDM, where all 16-bit Windows applications are loaded and executed as 
separate threads of a single VDM process. The VDM calls the Win32 subsystem —and 
occasionally the NT executive — to perform tasks on its behalf, such as windowing 
operations. 

This architecture allows all 16-bit Windows applications to run in the same virtual 
address space (as they must to be compatible with Windows 3.1) and gives DOS 
applications the illusion of having a DOS environment all to themselves. Windows NT 
also provides for process isolation, which is fundamental to protecting the integrity 
of Windows NT processes. This VDM layer allows “most" 16-bit applications to run 
under Windows NT without modification. 

The problem is the hardware-dependent 16-bit applications, such as a DOS pro¬ 
gram that directly accesses a scanner or other non-standard hardware device. Under 
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Device Drivers 


Paula Tomlinson 

Windows NT, only kernel-mode drivers have sufficient privilege to perform DMA or 
directly access I/O ports or perform memory-mapped I/O. Therefore, when 16-bit 
applications attempt these operations, the VDM intercepts the attempt and routes it 
to the kernel-mode driver that is allowed to perform the direct hardware access. The 
Virtual Device Driver (VDD) interface, with the help of the VDM, provides a way for 
hardware-dependent 16-bit applications to work under both 16-bit environments 
(Windows 3.1 and DOS) and Windows NT. The VDD serves as a bridge between the 
16-bit application and the 32-bit kernel-mode driver. When 16-bit applications at¬ 
tempt a privileged hardware access, the operation is typically intercepted by the 
VDM and sent to the VDD, where it is translated into a request for the appropriate 
kernel-mode driver. Windows NT provides standard VDDs for the mouse, keyboard, 
parallel ports, serial ports, and the display. Additional VDDs can be created fairly 
easily. 

Windows NT supports the SCSI interface through a layered set of kernel-mode 
drivers, as shown in Figure 1. Win32 applications access SCSI devices at the '‘Class’’ 
driver layer by using the Win32 file API. Each SCSI Class driver supports a specific 
category of device types, such as hard disks, CD-ROMs, or scanners. Supporting a 
new type of SCSI device typically requires writing only a Class driver. The next layer 
is the SCSI Port driver. There is a single SCSI Port driver for each platform (e.g., one for 
Intel platforms, one for MIPS platforms, and so on). The Port driver is responsible for 
all synchronization operations and for any operating system or platform-dependent 
operations. This allows the Class and Miniport drivers to be portable across platforms. 
The Miniport drivers support specific host bus adapters (HBAs), such as Adaptec 154x 
series and the NCR 53c700 series. The Miniport drivers isolate the Port and Class 
drivers from any HBA-specific details. 

When you first boot Windows NT, it calls each Miniport driver’s initialization 
routine. The Miniport driver calls the Port driver’s initialization routine and its own 
HwFindAdapter routine to look for any corresponding HBAs installed. The Port driver 
scans through all possible targets and gathers inquiry data for each logical unit. 
When the Class drivers initialize, they access this INQUIRY information and claim any 
devices that match their device type. For instance, the newly developed SCSI Scanner 
Class driver (not available on the October build of Windows NT) claims any Scanner 
device types ( 06H) or Processor device types (03H). Notice that since devices are 
found and claimed at initialization time, all SCSI devices must be powered on when 
Windows NT boots or they won’t be recognized. 


Deciding Which VDD Intercept Method to Use 

There are two methods for implementing VDDs, again as shown in Figure 1. The 
methods are distinguished by who performs the intercepting of the hardware access 
—the VDM or a portion of the 16-bit application (typically a 16-bit driver). 

In the first method, you would modify the 16-bit application or driver to replace 
any direct hardware access with calls to its companion VDD, which then routes 
these requests to the appropriate kernel-mode driver. The intercept in this case 
occurs at a high level as compared to intercepting attempts to directly manipulate 
the hardware. This typically results in better performance, but requires rewriting part 
of the application or, at the very least, replacing the 16-bit driver with a stub driver 
that calls the VDD. 
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X-32VM 


* Real & protected mode 16-bit support 

* 32-bit protected mode support 

► Wide range of graphic adapter support 

* Virtual screens 

* Multiple simultaneous graphics adapters 

* BGI interface available 

$250, No Royalties 


X-32VJVI 32-bii DOS Extender 

•Ip to 3.5 gigabytes of virtual memory 
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• Flash Graphics and Flash View compatible 
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products, by the original authors, now with 
support for other compilers. New features, 
fantastic support, no royalties, and great 
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FlashTek, Inc. 

121 Sweet Ave. 

Moscow, Idaho 83843 
Info: 208-882-6893 

Email: flasb@proto.com 

FAX: 208-882-7275 


800-397-7310 
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Voice: +44-476-74108 
Fax: +44-476-61382 


Borland, BGI, Watcom and Zortech are trademarks of 
their respective companies. 
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In the second method, you let the 
VDM intercept the hardware access at a 
very low level. The VDD hooks the uni¬ 
que range of 1/0 ports and/or memory 
areas it uses. When the application or 
driver tries to access these ports or 
memory locations, the VDM intercepts 
the operation and routes it to the ap¬ 
propriate VDD. The VDD then calls the 
kernel-mode driver to perform the ac¬ 
tual hardware access. Although perfor¬ 
mance usually suffers with this method, 
no portion of the 16-bit application or 
driver requires modifications. 

Finally, you could use a combination 
of application and VDM-based intercept 
methods. This would allow you to inter¬ 
cept time-critical operations at a higher 
level in the stub driver and use the 
VDM-intercept method for the remain¬ 
ing, less performance-driven, operations. 

Since most applications supporting 
the HP scanners use a common DOS 
device driver to communicate with the 
scanner, I chose the first method. This 
method yields better performance and 
is really no more difficult to implement 
than the second method. It required 


writing a replacement stub DOS device 
driver and an application-based inter¬ 
cept VDD. The 16-bit applications them¬ 
selves required no changes, since the 
stub DOS device driver supplied the 
same interface as the original DOS 
device driver. Since VDDs are imple¬ 
mented as 32-bit DLLs, you can also use 
them to export a 32-bit device API for 
your future Win32 applications. 
Remember that the three kernel-mode 
SCSI driver layers I needed already ex¬ 
isted —it’s a bit more work if you need 
to add a SCSI Class driver. 

Creating the Stub DOS 
Device Driver 

For those who are rusty on the fun¬ 
damentals of writing DOS device drivers, 
I’ll briefly describe the source code for 
hpscanl6.sys, the stub DOS device 
driver shown in hpscanl6.asm (Listing 1) 
and hpscanl6.inc (Listing 2). In the 
description, I’ll refer to DOS, since it is 
Windows NT’s job to accurately and 
fully simulate any DOS operations the 
DOS device driver relies on. It isn’t 


Figure 1 Windows NT SCSI interface support 
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necessary to be a DOS device driver expert; this driver is truly 
a “stub." 

At offset zero, all DOS device drivers are required to have a 
Device Header structure, which I have called SCAN_HEADER. The 
Device Header defines five key values for DOS. The first 
double-word value is initialized to -1. DOS will fill it in at run¬ 
time with a pointer that forms a linked list of all the DOS 


device drivers. The second word field describes attributes of 
the driver; in particular, it specifies whether it is a character- 
or block-mode device. My scanner driver is a character-mode 
device (it transfers data one byte at a time) and supports I/O 
controls (lOCTLs), so I have set bits 15 and 14, resulting in a 
value of 0C000H. The next two word fields specify the offsets 
of the “strategy” and "interrupt” routines for the driver. The 


Listing 1 

hpscan16.asm — Stub DOS device driver 




■MODEL small 







************************************ 

mov 

cs:STK PTR.sp 

;save original stack ptr 


Filename: 

hpscan!6.asm 

mov 

cs:STK SEG.ss 

;save original stack seg 


Purpose: Stub DOS Device Driver. Pass device 

cl i 


;disable for stack ops 


"HPSCAN” requests to the VDD, hpscan32.dll. 

mov 

ax.cs 

; setup new stack ptr 


Environment: 

MSDOS, Windows NT. 

mov 

ss.ax 

;setup new stack seg 


(C) Hewlett- 

Packard Company 1993. 

mov 

sp.offset TOP 

STK 


************* 

************************************ 

sti 


•.restore flags back 

INCLUDE hpscan!6.inc ;private 

cld 


;al1 moves are forward 

INCLUDE isvbop 

.inc ;NT DDK 







les 

bx,cs:RH PTRA 

;load req hdr adr in es:bx 

SUBTTL Segment and data definitions 

mov 

al.RH.RHC CMD 



ASSUME 

CS:CSEG,DS:NOTHING,E$:NOTHING 

cmp 

al ,0 

;check for init command 

CSEG SEGMENT 


je 

BOOTUP 

;command 0 = init 




xor 

dx.dx 

;some other command 


Resident data area - variables needed after init 

mov 

dl.RH.RHC CMD 

;dx - coimiand code 




mov 

cx.RH.RHC CNT 

;cx = count 




mov 

ax.RH.RHC SEG 

;es:bx = addr of data 


**— Device 

Header, must be at offset zero —** 

mov 

bx.RH.RHC OFF 


SCAN HEADER: 


mov 

es,ax 

;finally, load VDD handle 


dd -1 

;becomes ptr to next req hdr 

mov 

ax,word ptr cs:[VDD hVDD] 


dw 0C000H ;character, supports IOCTL 

DispatchCal1 

;cal 1 Dispatch in VDD 


dw offset STRAT ;Strategy routine 



•.returns with status in di 


dw offset IDVR ;Interrupt routine 

EXIT: 



DH NAME db 'HPSCAN ' ;char device name 

les 

bx,cs:RH PTRA 

•.restore ES:BX 




or 

di.STAT DONE 

;add "DONE" bit to status 


**- Request Header addr, saved by STRAT -** 

mov 

RH.RHC STA.di 

;save status in requ hdr 

RH PTRA LABEL 

DWORD 

cl i 


;disable ints for stack op 

RH PTRO 

dw ? -.offset 

mov 

ss,cs:STK SEG 

;restore stack seg 

RH PTRS 

dw ? ;segment 

mov 

sp,cs:STK PTR 

;restore stack ptr 




sti 


;re-enable interrupts 


**_ 

— Define Stack Space -** 




STK SEG dw ? 

;Save original stack segment 

pop 

bp 

;restore registers 

STK PTR dw ? 

;Save original stack pointer 

pop 

si 


STACK dw 200 DUP (0) ;Local stack 

pop 

di 


TOP STK dw ? 

;Top of local stack 

pop 

dx 





pop 

cx 



**_ 

-VDD information-** 

pop 

bx 


VDD Dll Name 

db "HPSCAN32.DLL", 0 

pop 

ax 


VDD InitFunc 

db “VDDInit", 0 

pop 

es 


VDD DispFunc 

db "VDDDispatch", 0 

pop 

ds 


VDD hVDD 

dw ? 

ret 


;far return 




IDVR endp 



** 

— Copyright Info-** 





db '(C) Copyright Hewlett-Packard Company 1993.' 

. ** 

---- jump here 

for Init Command-** 


db 'All rights reserved.' 

BOOTUP: 






mov 

ax,offset EndDriver 

SUBTTL Device 

Strategy & Interrupt entry points 

mov 

RH.RHC OFF,ax 

;address of end of driver 




mov 

RH.RHC SEG.CS 

;reference from code seg 


** 

- STRAT routine -** 




STRAT proc far ;Strategy routine 

mov 

si,offset VDD 

Dll Name ;load regs for VDD 


mov cs:RH 

PTRO.bx ;save offset address 

mov 

di,offset VDD 

InitFunc 


mov cs:RH 

PTRS.es ;save segment address 

mov 

bx,offset VD0 

DispFunc 


ret 

;end Strategy routine 

RegisterModule 

;calls the VDD 

STRAT endp 


jnc 

save hVDD 

;if NC then success 




mov 

di.STAT GF 

;set failure status 


**_ 

-IDVR routine-** 

jmp 

EXIT 

;return via common exit 

IDVR proc far interrupt routine 





push ds 

;save all modified registers 

save hVDD: 



push es 

;DOS has stack for 20 pushes 

mov 

[VDD hVDD],ax 

;save handle in ax 


push ax 


mov 

di.STAT OK 

;load OK status 


push bx 


jmp 

EXIT 

;return via common exit 


push cx 






push dx 


EndDriver db ? 



push di 


CSEG 

ENDS 



push si 



END SCAN HEADER ;REQUIRED BY EXE2BIN 


push bp 


; End of 

File 
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last value contains an eight-byte unique name that applica¬ 
tions use to access the driver. Because my goal is to require 
no changes to any 16-bit applications that access my original 
DOS device driver, the stub's device header must be identical 
to my original DOS device driver's Device Header. 

DOS device drivers get called twice to process each com¬ 
mand. The first time, the strategy routine specified in the 
Device Header is called; the second time, the interrupt routine 
is called. This two-call scheme was based on the design of 
UNIX device drivers, but the strategy routine in DOS device 
drivers invariably does next to nothing. 

The strategy routine ( STRAT) in my device driver stub just 
saves the request header address that DOS placed in ES:BX. 
The include file in hpscanl6.inc (Listing 2) sets up a general 
structure (RHC) for the request header (the actual contents of 
the request header depend on the command requested by 
the calling DOS application). The request header contains all 
the information necessary to carry out the requested com¬ 
mand, including the command code. 

The interrupt routine ( IDVR ) examines the request header 
and determines what command (such as a read or write) the 
DOS application is requesting. I chose to make the stub driver 
as generic as possible, so the IDVR routine passes all com¬ 
mands to the VDD except for the Initialization command DOS 
sends when it first loads the device driver. This means that if I 
add extensions later, I only have to change the VDD, not the 
DOS device driver stub. 

For the Initialization command, the IDVR routine loads the 
name of the VDD in DS:SI, the address of the VDD’s initializa¬ 


tion routine (the routine called when the VDD loads) in DS:DI, 
and the address of the VDD's dispatch routine (the routine that 
handles requests) in DS:BX. Then the IDVR routine executes the 

(text continued on page 17) 


Listing 2 hpscan16.inc — Defines for stub DOS 
device driver 


.************************************************* 
; Name: HPSCAN16.INC 

; Description: Defines for HPSCAN16.ASM 
.************************************************* 


;**-Segment Declarations - 

CSEG segment word public 'CODE* 

CSEG ends ;header segment 

- Status Values - 

equ OOOOh ;ok 

equ OlOOh ;function complete 

equ 800Ch ;general failure 

RH EQU ES: [BX] ;request header 


STAT_0K 
STAT DONE 

stat”gf 


;**- Common Request Header Structure -** 

RHC struc ;common to all commands 

db ? ;1ength of request header 

db ? ;unit code of device 

RHC_CMD db ? ;command code 

RHC_STA dw ? ;completion status, 16-bits 

dq ? ;reserved for DOS 

db ? ;this field varies with command 
RHC_0FF dw ? ;offset of data 
RHC_SEG dw ? ;segment of data 

RHC_CNT dw ? ;byte count (length) of data 

RHC ends ;end of common portion 
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MICROSOFT WANTS TO 
UPGRADE ITS RELATIONSHIP 
WITH DEVELOPERS. 


The Microsoft 
visual develop¬ 
ment tools team. 
Clockwise from left: 
Sanjay Shenoy, 
Nancy Schoeggl, 
Rick Olson, 

David Gray, 

Alan Ezekiel, 

Sean Shapiro and 
Kathleen Herald. 


You’re a developer. 

You’re the most important part 
of this technological revolution 
designed to make everyone’s life eas¬ 
ier. And we think it’s about time 
somebody started making your life 
a little easier. 

We’re the Microsoft’ visual devel¬ 
opment tools team. 

Developers just like you, who 
want to create innovative appli¬ 
cations for the Windows™ operating 
system, but know that change 
doesn’t always come easy. So we’ve 
dedicated ourselves to doing 
something about that. Something 
remarkable, thanks to you. 

You’ve been telling us you want 
certain things.You want to move to 
development for Windows, but you 
don’t have the time to learn how 
to program all over again. 

You want to work in a visual 
environment, but you can’t afford 
to lose power and speed. 

You want to focus on creativity, 
but the mundane keeps getting in 
the way. And most of all, you want 
straight answers to straight ques¬ 
tions about Microsoft products. 

Well, we listened. 
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WE STARTED BY 
UPGRADING 
OUR DEVELOPMENT 
TOOLS. 


a. The Visual C++ 
integrated environ¬ 
ment. b. Visual C++ 
AppWizard dialog 
box. c. Visual Basic 
custom application. 

d. Visual Basic 
Properties window. 

e. Customize appli¬ 
cations with VBX 
controls, f. Source 
code protection 
with Delta. 


Now you can make your com¬ 
mon tasks simple and your complex 
tasks possible with new Visual C++,” 
Visual Basic™ 2.0, Visual Control 
Pack and Microsoft’ Delta. 

The development environment 
in Visual C++ is totally integrated. 
The tools aren’t just slapped to¬ 
gether, they’re aware of each other’s 
state. Which means now you can 
work with tools that seem to know 
what you want to do next. But 
don’t worry, you won’t lose any 
power or flexibility. 

Also the Visual C++ develop¬ 
ment system gives you your own 
programming assistant, appropri¬ 
ately called a wizard. Actually you 
get two wizards, AppWizard and 
ClassWizard. AppWizard creates a 
complete ready-to-run application 
framework. And ClassWizard 
connects the user interface to your 
code. Both wizards are designed 
to work with Microsoft Foundation 
Class Library version 2.0. Which 
means you inherit the most innova¬ 
tive Windows-based features. 
Just like that. 

Programming changed back 
in 1991. Visual Basic 1.0 made it 
visual. And fast. 

Now in 1993, Visual Basic pro¬ 
gramming system 2.0 gives you over 
150 improvements - a Properties 
window, a full-featured debugger 


and intergrated data access via 
ODBC. But what they all boil down 
to is more power: 35% faster EXEs. 
And twice the capacity. 

Both Visual Basic and Visual 
C++ let you select from over a hun¬ 
dred VBX controls - everything 
from database communication to 
charting and multimedia. 'fou can 
get these controls from Microsoft 
Visual Control Pack or from our 
third party catalogs. So you can add 
more functions without adding 
more code. 

If you’ve got a whole develop¬ 
ment team working on a project, 
you need to protect your code. 
Microsoft Delta gives you hassle- 
free source code control. And 
it’s the visual way to document all 
your team’s source code. Which 
means fewer bad things can happen 
to good code. 

We’re proud of these tools. 
And we can’t wait to get them into 
your hands. To upgrade your 
applications for Windows, see your 
local reseller. 

The tools you see here are 
just the beginning. And we promise, 
you won’t have to wait years for 
the upgrades. 
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We’re all in the communication 
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(continued from page 11) 

RegisterModule macro (for details on how these macros 
work, see the sidebar, “The VDD Backdoor”). On return from 
the macro, the IDVR routine saves the handle to the VDD that 
was placed in AX. The carry flag is set if an error occurred. If 
there are opportunities for your driver to fail initialization after 
RegisterModule was called, then the driver should call Un- 
RegisterModule before it exits. 

One note: in the October build, the address of the Initializa¬ 
tion routine is specified in DS:DI. In subsequent builds, this 
may be changed to ES:DI. 

For all other commands, the IDVR routine loads the handle 
of the VDD in AX and executes the DispatchCall macro. The 


stub driver and the VDD can agree on using any other 
registers as private parameters. I chose to load the command 
code in DX, the transfer length in CX, and the address of the 
request header in ES:BX. The DispatchCall macro transfers 
control to the dispatch routine in my VDD. The VDD returns a 
status value in DI and the transfer length in CX. Finally, the stub 
driver cleans up and returns to the calling DOS application. 

I used the following commands to build a stub driver that 
incorporates my 16-bit tools: 

masm /mx hpscanl6.asm,,nul.Ist.nul .erf; 

link /M /L hpscanl6; 

exe2bin hpscanl6.exe hpscan!6.sys 


Listing 3 hpscan32.c - Windows NT VDD for HP scanner 


/** _____________ ** 

** HPSCAN32.C: HP Scanner Application-based VDD. 

** Environment: Windows NT. 

** (C) Hewlett-Packard Company 1993. 

**__** j 

♦include <windows.h> 

♦include <devioctl.h> 

♦include <ntddscsi.h> 

♦include <vddsvc.h> 

♦include <stdio.h> /* prototype for sprintf */ 

♦include “hpscan32.h" 

/**.Global s.**/ 

HANDLE hScanner=NULL; /* handle to scanner driver */ 
PASS_THROUGH_STRUCT PassThru; 

/** . 

** VDDLibMain - serves as LibMain for this DLL. 

**____ __ -k-k J 

BOOL VDDLibMain(HIN$TANCE hlnst, ULONG ulReason, 

LPVOID IpReserved) 

{ 

switch (ulReason) 

( 

case DLL_PROCESS_ATTACH: 

if ((hScanner * HPScannerOpen()) == 
INVALID_HANDLE_VALUE) return FALSE; 
break; 

case DLL_PROCESS_DETACH: 

HPScannerClose(hScanner); 
break; 

default: break; 

) 

return TRUE; 

) /* VDDLibMain */ 

/**. 

** VDDInit - Called when HPSCAN16.SYS initializes, via 
** the BIOS Operation Manager. 

** _______ *+/ 

VOID VDDInit(VOID) 

( 

setCF(O); /* Clear flags to indicate success */ 

return; 

) /* VDDInit */ 

/**. 

** VDDDispatch - called when HPSCAN16.SYS sends a request. 

** Arguments: 

** Client (DX) = Command code 

** Client (CX) - Buffer size 
** Client (ES:BX) * Request Header 
** Returns: 

** (CX) - Count transfered 


(DI) - status 


VOID VDDDispatch(VOID) 

( 

PCHAR Buffer, DrvBuffer; 

USHORT cb, i=0; 

ULONG bytes=0L, ulAddr, ulIoAddr; 

PHPSCANJOCTL ploctl; 

if (hScanner -= NULL) return; 

/* client put the count in cx, request header in es:bx */ 
cb = getCX(); 

ulAddr = (ULONG)MAKELONG(getBX(), getES()); 
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Listing 3 continued 


Buffer = (PCHAR)GetVDMPointer(ulAddr, (ULONG)cb, FALSE); 

switch (getOX()) /* command code is in dx */ 

{ 

case CMD_READ: 

if ((bytes ■ HPScannerRead(hScanner, Buffer, 

(ULONG)cb)) == NULL) setDI(STAT_GF); 
else setDI(STAT_OK); 
setCX((USHORT)bytes); 
break; 

case CMD_WRITE: 
case CMD_WRITE_VFY: 

if ((bytes = HPScannerWrite(hScanner, Buffer, 

(ULONG)cb)) == NULL) setDI(STAT_GF); 
else setDI(STAT_0K); 
setCX((USHORT)bytes); 
break; 

case CMD_OUT_IOCTL: 

ploctl = (PHPSCAN_IOCTL)Buffer; 
ulIoAddr = (ULONG)MAKELONG(pIoctl->0ffset, 
ploctl->Segment); 

DrvBuffer = (PCHAR)GetVDMPointer(ulIoAddr, 

(ULONG)ploctl->Count, FALSE); 
if ((ploctl->Count = (USHORT)HPScannerlOCTL(hScanner, 
ploctl->Command, DrvBuffer, (ULONG)ploctl->Count)j 
!= NULL) setDI(STATOK); 
else setDI(STATCE); 

FreeVDMPointer(ulIoAddr, (ULONG)pIoctl->Count, DrvBuffer, 
FALSE); 
break; 

default: 

setDI(STAT_CE); /* unsupported command */ 

break; 

) 

FreeVDMPointer(ulAddr, (ULONG)cb, Buffer, FALSE); 
return; 

} /* VDDDispatch */ 

!** ___ 

** VDDScannerCommand - 32-bit private API 

**___ ** j 

ULONG API ENTRY VDDScannerCommand(USHORT usCommand, 

PCHAR pcBuffer, ULONG ulLength) 

{ 

switch(usCommand) 

f 

case CMD_READ: 

return HPScannerRead(hScanner, pcBuffer, ulLength); 
case CMD_WRITE: 

return HPScannerWrite(hScanner, pcBuffer, ulLength); 

case CMD_IOCTL_READBUFFER: 
case CMD_IOCTL_WRITEBUFFER: 
case CMD_IOCTL_SCSIINQ: 

return HPScannerIOCTL(hScanner, usCommand, pcBuffer, 
ulLength); 

default: return NULL; 

) 

return NULL; 

) /* VDD_ScannerCommand */ 

/**- private routines -**/ 

— . — . — — - — • — — - — — 

** HPScannerOpen - returns handle to scanner device 

** _____ ** / 

HANDLE HPScannerOpen(VOID) 

{ 

/* for simplicity, we'll assume only one scanner */ 
return CreateFile((LPTSTR)"\\\\.\\ScannerO“, 


When a VDM loads, it checks config.nt 
for any 16-bit DOS device drivers that 
might be required by 16-bit applications 
running in the VDM. To ensure that my 
stub DOS device driver is available to all 
16-bit applications, I added the follow¬ 
ing line to the config.nt file: 

device={path}hpscanl6.sys 

Creating the Application- 
Based Intercept VDD 

The source code for the HP Scanner 
VDD, hpscan32.dll, is in hpscan32.c 
(Listing 3), hpscan32.h (Listing 4), 
hpscan32.def (Listing 5), and sources 
(Listing 6). A VDD is really just a Win32 
DLL that exports some specific routines 
known by the stub DOS device driver. 
First, notice that there is no LibMain() 
or UEP() routine in this DLL. Win32 DLLs 
have one entry point that Windows NT 
calls when a process or thread attaches 
to or detaches from the DLL. The name 
of the entry point is specified in the 
link line of your makefile (“link - 
entry :VDDLibMain ...”) or the 
DLLENTRY line of a sources file 
(“DLLENTRY=VDDLibMain"). To reinforce 
this point, I named my DLL's entry point 
VDDLibMain(). Notice that the 
prototype for the entry point has 
changed from the old Windows 3.1 
LibMain()\ 

The only entry point parameter I 
care about, in this case, is Reason. This 
parameter can have the following 
values: DLL_PROCESS_A TTACH, 
DLL_PROCESS_DETACH, DLL_ THREAD_A T- 
TACH, or DLL_THREAD_DETACH. Since 
threads inherit handles from their 
parent process, I am only interested in 
processes attaching and detaching. 
When a process attaches, I attempt to 
open the scanner device, and when a 
process detaches, I close the scanner 
device. 

VDDInit() and VDDDispatch () are 
called, respectively, when the DOS stub 
device driver initializes and sends re¬ 
quests. VDDInit() would be a good 
place to allocate any necessary resour¬ 
ces. VDDDispatch () deciphers the 
register contents agreed upon by the 
stub driver and sends a read, write, or 
IOCTL command to the hardware 
device. VDM provides a complete set of 
register manipulation routines, such as 
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Listing 3 continued 


getAX(). (On RISC machines, these 
routines use virtual registers maintained 
by x86 emulator.) You should use these 
routines to access any registers set by 
the stub driver. Another complication 
arises from the fact that the address in 
ES:BX is in segment:offset form. 

GetVDMPointerf) translates DOS seg- 
ment:offset- or selector-.offset- style 
pointers to 32-bit linear addresses. 

Now that I have a Win32 DLL that 
knows how to communicate with the 
SCSI kernel-mode drivers to access an 
HP scanner, I might as well add a 32-bit 
API so that any new Win32 applications 
I write can also easily access the scan¬ 
ner. The VDD exports the VDDScanner- 
Comand() routine for this purpose. It 
requires only three simple parameters: 
an ID to identify the command 
(CMD_READ, CMDJ/RITE, or CMDJOCTL), an 
address of a buffer, and the length of a 
buffer. The command requested indicates 
what action to take with the buffer. 

HPScannerOpen() uses Create- 
File() (a Win32 function) to open a 
handle to the device. A value of zero for 
the ShareMode parameter prevents the 
file/device from being shared. To 
simplify the example, I am assuming 
that only one scanner exists and that it 
is an HP scanner. A better solution is to attempt opening 
ScannerO through ScannerN (the name the Class driver 
registers for itself), and to check the INQUIRY data for each 
scanner found to determine if it is your scanner. 

HPScannerClose (), HPScannerRead() , and HPScanner- 
Urite() routines just call the corresponding Win32 API func¬ 
tion, using the handle to the open scanner device and the 
buffer passed by the calling program. 

HPScannerIOCTL() uses DeviceIoControl() (a Win32 func¬ 
tion) to send IOCTL requests to the scanner device. Some very 
common SCSI lOCTLs, such as “Inquiry," are supported by a 
common SCSI Class driver. Some SCSI Class drivers support ad¬ 
ditional lOCTLs that are pertinent to that category of device. 
The SCSI Scanner Class driver is very generic and does not 
support any lOCTLs itself. The SCSI kernel-mode drivers provide 
a method, called “Pass Through," to allow applications to send 
any command to a SCSI device. The HP scanners support many 
lOCTLs that aren't explicitly supported. For simplicity, I have 
included only the “Read Buffer,” “Write Buffer," and “Inquiry" 
lOCTLs using the “Pass Through" mechanism (I could have used 
a direct IOCTL command, IOCTL_SCSI_GET_INQUIRY_DATA, for 
the “Inquiry” IOCTL). 

I fill in a structure called PASS_THROUGH_STRUCT (defined in 
hpscan32.h) which has a SCSI_PASS_THROUGH structure 
(defined in NT’s ntddscsi.h) embedded in it. There are two 
unusual things here that are worth mentioning. First, you 
would naturally think that the Dataln field of the 
SCSI PASS THROUGH structure would refer to the direction of 


GENERIC_READ | GENERIC_WRITE, 0, NULL, 

0PEN_EXISTING, FILE_ATTRIBUTE_NORMAL, NULL); 

} /* HPScannerOpen */ 

/**. 

** HPScannerClose - close handle passed in 

**___** j 

BOOL HPScannerClose(HANDLE handle) 

{ 

return CloseHandle(handle); 

) /* HPScannerClose */ 

/**. 

** HPScannerRead 

**___** j 

ULONG HPScannerRead(HANDLE handle, PCHAR buffer, ULONG len) 

( 

DWORD cnt=0; 

if (!(ReadFile(handle, buffer, len, &cnt, NULL))) 
return NULL; 
else return cnt; 

) /* HPScannerRead */ 

/**. 

** HPScannerWrite 

**_** j 

ULONG HPScannerWrite(HANDLE handle, PCHAR buffer, ULONG len) 

{ 

DWORD cnt=0; 

if (!(WriteFile(handle, buffer, len, &cnt, NULL))) 
return NULL; 
else return cnt; 

) /* HPScannerWrite */ 
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SuperCom is fast even in a multitasking operating system 
like Windows. 
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Listing 3 continued 


__ 

** HPScannerlOCTL 

** __ ------------ _ **/ 

ULONG HPScannerlOCTL(HANDLE handle, USHORT usCommand, 

PCHAR pBuffer, ULONG ulLength) 

{ 

USHORT i=0; 

DWORD bytes=OL; 

/* clear CDS and data buffer before IOCTL call */ 
memset(PassThru.ucDataBuf, 0, sizeof(PassThru.ucDataBuf)); 
for (i=0; i <= 16; 1++) PassThru.sptCmd.Cdb[i] = 0; 

PassThru.sptCmd.Length ■ sizeof(SCSI_PASS_THROUGH); 
PassThru.sptCmd.SenselnfoLength = 
sizeof(PassThru.ucSenseBuf); 

PassThru.sptCmd.DataTransferLength = ulLength; 
PassThru.sptCmd.TimeOutValue = 10; 

PassThru.sptCmd.DataBufferOffset = PassThru.ucDataBuf 

- (UCHAR*)&PassThru; 

PassThru.sptCmd.SenselnfoOffset = PassThru.ucSenseBuf 

- (UCHAR*)&PassThru; 

switch(usCommand) 

( 

case CMD_IOCTL_READBUFFER: 

PassThru.sptCmd.CdbLength = 10; 

PassThru.sptCmd.Dataln « TRUE; 

PassThru.sptCmd.Cdb[0] « 0x3c; 

PassThru.sptCmd.Cdb[l] = 2; 

PassThru.sptCmd.Cdb[7] = HIBYTE(ulLength); 
PassThru.sptCmd.Cdb[8] = LOBYTE(ulLength); 

DeviceloControl(hScanner, IOCTL_SC$I_PASS_THROUGH, 
APassThru, sizeof(SCSI_PASS_THROUGH), &PassThru, 
sizeof(PassThru), &bytes, FALSE); 
memcpy(pBuffer, PassThru.ucDataBuf, 

PassThru.sptCmd.DataTransferLength); 
return PassThru.sptCmd.DataTransferLength; 

case CMD_IOCTL_WRITEBUFFER: 

PassThru.sptCmd.CdbLength = 10; 

PassThru.sptCmd.Dataln = TRUE; 

PassThru.sptCmd.Cdb[0] = 0x3b; 

PassThru.sptCmd.Cdb[l] * 2; 

PassThru.sptCmd.Cdb[7] = HIBYTE(ulLength); 

PassThru.sptCmd.Cdb[8] = L0BYTE(ulLength); 

memcpy(PassThru.ucDataBuf, pBuffer, ulLength); 
DeviceloControl(hScanner, IOCTL_SCSI_PASS_THROUGH, 
&PassThru, sizeof(PassThru), &PassThru, 
sizeof(PassThru), &bytes, FALSE); 
return PassThru.sptCmd.DataTransferLength; 

case CMD_IOCTL_SCSIINQ: 

PassThru.sptCmd.CdbLength = 6; 

PassThru.sptCmd.Dataln = TRUE; 

PassThru.sptCmd.Cdb[0] = 0x12; 

PassThru.sptCmd.Cdb[4] = (UCHAR)ulLength; 

DeviceloControl(hScanner, IOCTL_SCSI_PASS_THROUGH, 
iPassThru, sizeof(SCSI_PASS_THROUGH), &PassThru, 
sizeof(PassThru), ibytes, FALSE); 
memcpy(pBuffer, PassThru.ucDataBuf, 

PassThru.sptCmd.DataT ransferLength); 
return PassThru.sptCmd.DataTransferLength; 

default: return NULL; /* invalid command */ 

) /* switch */ 
return NULL; 

) /* HPScannerlOCTL */ 

/* End of File */ 


the data transfer. In the October build, 
my code only worked if I always 
specified TRUE, no matter which direc¬ 
tion the transfer was in. This may be a 
bug that will be fixed in later releases, 
or I may be misinterpreting the mean¬ 
ing of this field. Second, the 
SCSI_PASS_THROUGH structure, the 
“Sense Data" buffer, and the “Data 
Transfer” buffer must be contiguous. 
This is very inconvenient since the data 
buffer is at an address specified by the 
calling application rather than the VDDI 
To solve this problem, I ended up al¬ 
locating storage for both buffers in the 
PASS_THROUGH_STRUCT and copying the 
data buffer to or from (the direction 
depends on the IOCTL) the buffer 
passed to the VDD. To make matters 
worse, in the kernel-mode SCSI drivers, 
this buffer ends up getting copied 
again I Because of all of this copying 
overhead (I have allocated a fairly large 
buffer, 64kb, in my VDD), it is best to 
make this buffer as small as possible. 

You could create a makefile for 
building the VDD, but, just for fun, I am 
using the new BUILD tool that comes 
with the NT DDK. The BUILD program 
uses a standard makefile and a custom 
sources file to build the sources in the 
current directory. The makefile contains 
only a reference to a makefile.def file 
and should never be edited. I started 
with a sources file from one of the DDK 
samples and just modified it for my 
needs. You can use the sources file in 
Listing 6 as a template for your VDD. 

There are two ways to load a VDD. 
By calling RegisterModulef) in my stub 
DOS device driver, I am in effect per¬ 
forming a LoadLibraryO on the VDD 
name specified in DS:SI. As long as the 
VDD is somewhere in the path, it will 
be loaded whenever my stub loads. A 
second method for loading a VDD invol¬ 
ves adding a reference to it in the 
registry. This causes the VDD to be 
loaded any time a new VDM is started. 
This means that if, for any reason, this 
VDD fails to load, the user will get an 
ominous message, and in some cases 
the entire VDM will be affected. You 
should use this method only if your 
VDD is essential to all VDMs. The follow¬ 
ing line is an example of specifying a 
VDD in the registry. Multiple VDDs can 
be specified by separating them with a 
NULL ('\0') (see Figure 2). 
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Listing 4 hpscan32.h — Defines for Windows NT 
VDD 


_ _ __________ _ _ * ★ 

** HPSCAN32.H: HP Scanner Application-based VDD. 

** Environment: Windows NT. 

** (C) Hewlett-Packard Company 1993. 

*★_**/ 

/**- DOS Device Driver Status Codes -**/ 

Idefine STAT_0K 0x0000 /* SUCCESS */ 

#define STAT_CE 0x8003 /* invalid command */ 

Idefine STAT_GF 0x800C /* general failure */ 


/**-DOS Device 

Idefine CMD_READ 
Idefine CMD_WRITE 
Idefine CMD_WRITE VFY 
Idefine CMD OUT IOCTL 


Driver Command Codes -**/ 

4 /* read command */ 

8 /* write command */ 

9 /* write with verify */ 

12 /* output I/O control */ 


/**-DOS Device Driver Subcommand Codes-**/ 

Idefine CMD_IOCTL_READBUFFER 0x09 
Idefine CMD_IOCTL_WRITEBUFFER OxOA 
Idefine CMD_IOCTL_SCSIINQ OxOD 

/**.PASS_THR0UGH_S1'RUCT. **/ 

typedef struct 

{ 

SCSI_PASS_THROUGH sptCmd; 

UCHAR ucSenseBuf[32]; 

UCHAR ucDataBuf[65536]; /* big! */ 

} PASS_THROUGH_STRUCT; 

/**- IOCTL Structure from the DOS Stub driver —**/ 

typedef struct 

{ 

USHORT Command; 

USHORT Status; 

USHORT Count; 

USHORT Offset; 

USHORT Segment; 

} HPSCAN_IOCTL; 

typedef HPSCAN_IOCTL *PHPSCAN_IOCTL; 

/**- HPSCAN32.C, private prototypes -**/ 

HANDLE HPScannerOpen(VOID); 

BOOL HPScannerClose(HANDLE); 

ULONG HPScannerRead(HANDLE, PCHAR, ULONG); 

ULONG HPScannerWrite(HANDLE, PCHAR, ULONG); 

ULONG HPScannerIOCTL(HANDLE, USHORT, PCHAR, ULONG); 


/**- HPSCAN32.C, public prototypes -**/ 

BOOL VDDLibMain(HINSTANCE, ULONG, LPVOID); 

VOID VDDInit(VOID); 

VOID VDDDispatch(VOID); 

ULONG APIENTRY VDDScannerComniand(USHORT, PCHAR, ULONG); 


/* End of File */ 


Listing 5 hpscan32.def - Module definition file for 
Windows NT VDD 


LIBRARY HPSCAN32 

DESCRIPTION 'Application-based VDD for HP Scanners.' 

EXPORTS 

VDDInit 

VDDDispatch 

VDDScannerCommand 


TCP/IP for Windows 


eE 


Telnet - H.P. 


file Disconnect Edit Settings 


File Host Options Help 


File Mail Help 


Mall - postmaster 


TO 


m m 


File Disconnect Serv 




2 Change [►] 
fn Cieale F*1 
□ Re-oveH 


□ Append Q 

□ Copy □ 

□ Delete □ 

□ Rename □ 


addilbl doc 
adlbl30b.doc 
at&Ldoc 



Requires only 6KB of base memory 
Implemented as 100% Windows DLL 
(not a TSR) 

■ All applications are both client and server 

■ Works concurrently with Netware, LAN Manager, 
Vines etc. 

■ Up to 64 concurrent sessions 


Developer Tools: 

Windows Socket API 
Berkeley 4.3 Socket API 
ONC RPC/XDR 
WinSNMP API 


Applications: 

TELNET (VT100,VT220),TN3270, 
FTP, TFTP SMTP/Mail, POP2, 
SNMP, PING, BIND, Statistics, 
and Custom 


Extensible SNMP Agent 

■ Includes MIBII, Workstation,Windows and 
DOS agents 

■ Dynamic registration of multipleagents, managers, 
and proxies 

■ WinSNMP API developers kit available 

■ Compatible with any SNMP manager 

■ Free with NEWT, Chameleon, and ChameleomVFS 

NFS Client/Server 

■ Network drives are mounted from within Windows 

■ Network printing in the background 

■ Up to 24 network drives 

■ Requires only 6KB of base memory 

■ Included in ChameleonAFS' 


For overnight delivery coll: 

B§ MManage 

(408) 973-7171 


m 
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Listing 6 Sources file for NT build command 


INDENTED_DIRECTIVES=1 

MAJ0RC0MP=hpscan32 

MINORCOMP=hpscan32 

TARGETNAME=hpscan32 
TARGETPATH=d:\article\vdd 
TARGETTYPE=DYNLINK 

TARGETLIBS=$(BASEDIR)\public\sdk\lib\*\kernel32.1 ib \ 
$(BASEDIR)\public\sdk\lib\*\ntvdm. lib 

DLLENTRY=VDDLibMain 
DLLBASE=0x2000000 

INCLUDES=c:\ntddk\private\ntos\inc 

S0URCES=hpscan32.c 

I386_S0URCES= 

MIPS_SOURCES= 

C_DEFINES=-DWIN_32 -DDEBUG 

UMTYPE=windows 

UMTEST= 

UMLIBS= 


Sample Programs 

test32.c (Listing 7) and test32.h (Listing 8) contain the 
source for a very simple Win32 program, test32. test32 links 
with hpscan32. lib so that it can access the scanner via V- 
DDScannerCommandO. First, it requests SCSI Inquiry information 
and displays the device type field in a dialog box. Then, it 
tests reading and writing to the device by writing data to the 
scanner in the form of an inquiry command for the scanner's 
model number, then reading the response string. The model 
number is also displayed in the dialog box. The module defini¬ 
tion file is in test32.def (Listing 9), the dialog box definition is 
in test32. rc (Listing 10), and the makefile is in test32.mak 
(Listing 11). 

This is a good opportunity to point out a few changes to 
makefiles for the Win32 version of nmake. I included 
ntwin32.mak in my makefile to provide some default macros 
for the names of the development tools, command-line op¬ 
tions, and flags. It is handy to use $(gui.libs) to include the 
basic set of Win32 libraries rather than figure out exactly 
which libraries you need, but you will get an annoying warn¬ 
ing for any libraries that don't get used. As with some other 
versions of nmake, in order to use a file name other than 
makefile, you must use the // option: for instance, nmake If 
test32.mak. You will also notice a new intermediate export 


The VDD Backdoor 


When it became apparent, at the July 1992 Win¬ 
dows NT Conference in San Francisco, that 16-bit 
hardware-dependent applications wouldn’t be sup¬ 
ported under Windows NT, it raised quite an outcry. By 
the October NT Device Driver Conference in Anaheim, 
the problem had been solved by the new VDD inter¬ 
face: 

RegisterModule 

db 0c4h, 0c4h, 58h, 0 

endm 

UnRegisterModule 

db 0c4h, 0c4h, 58h, 1 

endm 

DispatchCall 

db 0c4h, 0c4h, 58h, 2 

endm 

So, how do these three innocent-looking macros pro¬ 
vide access to the VDM and, ultimately, your VDD? The 
answer is very clever. 

In isvbop. inc, you will find macro definitions for 
the three “routines’’ that 16-bit applications/drivers use 
to call their 32-bit VDD. But they aren’t routines at all. 
In each case, the macros expand into four bytes of 
data. The first two bytes are always C4C4H. This 
decodes into the instruction: 


LES AX, SP 

This is an invalid instruction, so it causes an excep¬ 
tion when the processor attempts to execute it. When 
the exception handler in the VDM processes this ex¬ 
ception, it first checks the byte immediately following 
the offending instruction. By placing a 58H at this loca¬ 
tion, you are in effect telling the VDM “I meant to do 
that!" Upon finding the 58H, the VDM checks the fol¬ 
lowing byte, which specifies whether the operation 
you intended to perform is a RegisterModule, Un¬ 
RegisterModule, or DispatchCall. This tells the VDM 
what values to expect in the registers and what values 
to load into the registers before it returns. And, of 
course, since it has added four bytes of nonsense to 
your code, it has to increment the instruction pointer 
past those bytes. Upon return from the exception 
handler, your original code can begin executing again. 
If you have trouble believing this, just use DEBUG or 
SYMDEB to unassemble your 16-bit driver 
(HPSCAN16.SYS). 

Remember that executing this code under a DOS 
environment will typically cause your program to hang, 
so make sure that end users only use your stub driver 
under Windows NT. □ 
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Changing Windows™ Applications into OS/2" Applications Is 

A Neat Trick Done With Mirrors 


M icrografx Mirrors can help you 
work magic. You can reach 
over a million new users for 
the price of an inexpensive tool kit. 

With Mirrors, you can maintain an 
application for two operating systems 
with a single set of 
source. This means 
you aren’t forced to 
choose between 
operating systems, 
and you won’t get 
bogged down in ver¬ 
sion control prob¬ 
lems and divided 
development efforts. 

Get the 

advantages of OS/2: 
access to a true 
multi-tasking operat¬ 
ing system, 32-bit architecture, a more 
stable platform, integration with other 
OS/2 applications, and a clear migration 
path — not to mention the advantage of 
a million new customers. 

How does it work? It’s simple. 
Mirrors emulates Windows. When your 


application, running under OS/2, calls a 
Windows function, Mirrors intercepts the 
call. Mirrors then implements it using 
functions within the OS/2 system DLLs. 
Mirrors transforms data returned by OS/2 
and passes it back in a form that 

Windows applications 
understand. Your 
application may never 
know that it’s not 
running under 
Windows. 

What do you 
need to do to make 
this happen? First, 
run Micrografx’s con¬ 
version utilities on 
your application’s 
resources, then re-link 
with the Mirrors 
DLL. That’s it. Using Mirrors, you 
may not even need to recompile. 
Micrografx developed the Mirrors technol¬ 
ogy. That means this tool kit was writ¬ 
ten by Windows developers for Windows 
developers. Mirrors is fast and inexpen¬ 
sive. Look into it! 



To Purchase your copy of Mirrors today, call (214) 994-6566. 

To learn more about how this trick is done, 
call Micrografx Technical Support for Mirrors at (214) 994-6659. 

• Mirrors is a 32-bit DLL for increased performance • 32-bit Mirrors DLL provides support for 16-bit applications 
■ Non-debug and debug version of Mirrors DLL provide handle validation and error reporting 
• Automated conversion of Help, bitmaps, cursors, and icons ■ Includes DOS and OS/2 host independent file HO libraries 
■ Interrupt 21 directly supported with no need to modify ASM files • DOS3CALL interrupt support 
■ Dynamic Data Exchange support with native PM applications ■ Mirrors also supports Clipboard data sharing 

MICROGRAFX® 

Micrografx, Inc. 1303 Arapaho, Richardson, TX 75081. Copyright © 1992, Micrografx, Inc. All rights reserved. Micrografx is a registered trademark 
of Micrografx, Inc. Windows is a trademark of Microsoft. OS/2 is a registered trademark of IBM Corporation. All other products are trademarks or 
registered trademarks of their respective ow ners. Mirrors is a trademark of Micrografx, Inc. Micrografx Mirrors is not affiliated with Softklone 

Distributing Corporation or Softklone's MIRROR data communications products. 
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Listing 7 test32.c — Windows NT test program for scanner VDD 

/********* TEST32.C - source file for test32.exe **********/ 

{ 

case WM INITDIALOG: 

linclude "windows.h" 

VDDScannerCommand(CMD IOCTL SCSIINQ, Buffer, 64); 

linclude "test32.h" 

wsprintf(TmpBuffer, "%c“, Buffer[0]+'0'); 
SetDlgltemTextfhDlg, ID SCSIINQ, TmpBuffer); 

/**-WinMain-**/ 


int APIENTRY WinMain(HINSTANCE hlnst, HINSTANCE hPrevInst, 

VDDScannerConmand(CMD_WRITE, l, \x0IB*sl0E", 64); 
VDDScannerCommand(CMD READ, Buffer, (ULONG)64); 

LPSTR lpCmdLine, int nShow) 

{ 

for (i=8; i <=12; i++) TmpBuffer[i-8] = Buffer[i]; 

DialogBoxfhlnst, MAKEINTRESOURCE(DISPLAY DLG), NULL, 

TmpBuffer[i-8] » 1 \0 1 ; 

DisplayDlgProc) ; 

SetDlgltemTextfhDlg, ID MODELNUM, TmpBuffer); 

return 0; 

return TRUE; 

) /* WinMain */ 



case WM COMMAND: 

/** ---DisplayDlgProc- **/ 

if (wParam == IDOK) EndDialog(hDlg, TRUE); 

BOOL CALLBACK DisplayDlgProc(HWND hDlg, UINT uMsg, 

return TRUE; 

WPARAM wParam, LPARAM 1Param) 


{ 

default: return FALSE; 

char Buffer[64+1], TmpBuffer[64+l], i; 

) 

return TRUE; 

switch (uMsg) 

) /* DisplayDlgProc */ 

/* End of File */ 


The Windows NT Registry 


The registration database that first appeared in 
Windows 3.1 contained information only for SHELL and 
OLE applications. At that time, Microsoft introduced an 
API for querying and setting values in the registration 
database. In Win32, the new database is called “the 
registry" and has been expanded significantly. You can 
still use the Windows 3.1 API, but Microsoft has added 
some extended versions of these routines. The Win32 
registry is intended to provide a single, consolidated 
source for configuration information, thus replacing the 
config.sys file and the proliferation of *. ini files. 

The kernel-mode SCSI driver layers require several 
entries in the registry. By the time the retail version of 
Windows NT ships, most or all of these additions 
should be made by either the Windows NT setup pro¬ 
gram, or a setup program shipped by the device 
manufacturer. For the October build, the SCSI port and 
miniport drivers corresponding to your SCSI Host Adapt¬ 
er (if available) are installed and loaded automatically. 
However, you must manually add some of the newer 
class drivers, such as the Scanner Class driver. To add 
the driver, first copy scsiscan.sys to the UINNT\SYS- 
TEM32\DRIVERS directory, then, use the RegEdit pro¬ 
gram to add the “ScsiScan" key and the values in Fig¬ 
ure 3. 

The DependOnGroup field specifies that the Scanner 
Class driver won't load unless at least one SCSI mini- 
port driver has already loaded. The ErrorControl 
value of Oxl specifies that the system will still boot 
even if the Scanner Class driver fails to load. The Group 


value specifies that this driver is a SCSI Class type of 
driver. The Start value of Oxl specifies that since this 
driver is not needed during the boot process, it will be 
loaded afterwards during the initialization process. The 
Type value of Oxl specifies that this driver is a kernel¬ 
mode driver rather than a user-mode driver. 

In order for devices to be accessible from the 
Win32 subsystem, a symbolic link object must be 
created in the Windows NT object namespace, 
\DOSDevices, to map Windows NT device names to 
Win32 logical names. The form generally used is 
\Device\GenericNameDigit. A fully functional Class 
driver would make this symbolic link automatically, 
but many of the Class drivers, including the Scanner 
class driver, are not yet fully functional so you may 
need to add the value in Figure 4. 

To confirm that the Class, Port, and Miniport drivers 
are all loading properly, you can browse through the 
HKEY_LOCAL_MACHINE\HARDUARE\DEVICEMAP\Scsi key. 
This key contains subkeys for each valid SCSI target ID 
and logical unit number. Inquiry information is dis¬ 
played for each device found. The Hewlett-Packard 
Scanners should report a string that contains the ini¬ 
tials “HP" and the model number of your scanner 
(C1790A or C1750A). 

Many changes to the registry don't take effect until 
you reboot. Also, keep in mind that the keys in the 
registry are very preliminary and may change for sub¬ 
sequent prerelease versions and for the final release of 
Windows NT. □ 


Page 24 — Windows/DOS Developer’s Journal 


May 1993 













/******** TEST32.H - include file for test32.exe ********/ 

fdefine IDNULL -1 

fdefine DISPLAYJLG 2000 

fdefine ID_SCSIINQ 2001 

Idefine ID_M0DELNUM 2002 

/**- DOS Device Driver Command Codes -**/ 

Idefine CMD_READ 4 

Idefine CMD_WRITE 8 

Idefine CMD_WRITE VFY 9 

Idefine CMD_OUT_IOCTL 12 

/**- DOS Device Driver Subcommand Codes -**/ 

Idefine CMD_I0CTL_READBUFFER 0x09 
Idefine CMD_I0CTL_WRITEBUFFER OxOA 
Idefine CMD_IOCTL_SCSIINQ OxOD 

BOOL CALLBACK DisplayDlgProc(HWND, UINT, WPARAM, LPARAM); 
ULONG APIENTRY VDDScannerCommand(USHORT, PCHAR, ULONG); 

/* End of File */ 


□ Request 109 on Reader Service Card □ 


file ( *.exp) that is used to build DLLs, as 
well as an extra resource compile step 
(cvtres) and an extra intermediary file 
(*. rbj). Some of the development tools 
documentation refers to these as tem¬ 
porary steps that won't be necessary 
for the final development tools. 


Figure 2 Sample specification of a VDD in the registry 


HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\VirtualDevice Drivers 
VDD:REG_MULTI_SZ:{pathlhpscan32.dll 


Listing 9 

test32.c 

test32.def - Module definition file for 

; TEST32.DEF 

- module definition file for TEST32.EXE 

NAME 

Test32 

DESCRIPTION 

“32-bit Test Program" 

EXETYPE 

WINDOWS 

STUB 

"WINSTUB.EXE" 

CODE 

PRELOAD MOVEABLE DISCARDABLE 

DATA 

PRELOAD MOVEABLE MULTIPLE 

HEAPSIZE 

1024 

STACKSIZE 

5120 

EXPORTS 



Listing 10 

test32.c 


test32.rc — Resource definitions for 


/****** TEST32.RC - resource file for TEST32.EXE *****/ 

linclude <windows.h> 
linclude "test32.h" 


DISPLAY_DLG DIALOG 40, 40, 140, 64 

STYLE WS_P0PUP | DS MODALFRAME | WS_VISIBLE | 

CAPTION "HP Scanner Test32" 

BEGIN 

CONTROL “Device Type: 11 , IDNULL, “static' 1 . 


WS CAPTION 


SS LEFT 1 WS CHILD, 20 

12, 70, 8 

CONTROL "“, ID SCSIINQ, “static", 

SS LEFT | WS CHILD, 92 

12, 40, 8 

CONTROL "HP Scanner Model 

l:“, IDNULL, “static", 

SS LEFT | WS CHILD, 20, 

24, 70, 8 

CONTROL "", ID M0DELNUM, “ 

static", 

SS LEFT 1 WS CHILD, 92, 

24, 40, 8 

CONTROL “&0K\ IDOK, “button", BS DEFPUSHBUTTON 1 

WS TABSTOP | WS CHILD, 

50, 42, 40, 14 

END 




Listing 11 test32.mak 

- Makefile for test32.exe 

# Nmake macros for building W 
linclude <ntwin32.mak> 

ndows 32-Bit apps 

all: test32.exe 


test32.rbj: test32.rc test32. 


rc -r test32.rc 

cvtres (CPU) test32.res 

-o test32.rbj 

test32.obj: test32.c test32.h 


$(cc) $(cflags) $(cvars) 

i(cdebug) test32.c 

test32.exe: test32.obj test32 

.rbj test32.def hpscan32.1ib 

$(cvtobj) $(cvtdebug) *.obj 

$(1ink) $(linkdebug) $(gu 

iflags) -out:test32.exe\ 

test32.obj test32.rbj 

hpscan32.1ib $(guilibs) 


Listing 8 test32.h — Header file for test32.c 


| LasiName | Sh 

1 Top Sales * 

Sales > 500 , 

Coleman CalHom 

0 

a 

Fesskr Massac 

L.0 _ 8...J 

te Texas 

Kaj&T a 


I; 

s 

1 

. 

— 

Spearman Michiga 


B 

Mite Arizona 


B 

Him in iCatsrari 


0 

Sawyer Wiscan 


□ 

Bradley Illinois 


B 

Hayen Maryian 


□ 

Smith Kaasas 

1 

I 0 

Jackson Florida 

0 

0 

Blake Indiana 


□ 

WHsoo. KM 


0 

5 

*r 



■ 3D Chart 
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■ Toolbox 
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groups 

■ Ribbon / Icon Bar 
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® Status Bar 

-Auto scrolled (ext ■ Field Validation 
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■ Meter Control 

-Creates vertical, horizontal and 
circular gauges with choice of 
needle or colorr bar as indicators 
-Linear & I algorithmic scales 

With source. Royalties Free. 30-Day MBG. 

Consulting & Contract Programming Available 
Kansmen Corporation Tel: (4081 988-0634 Fax: (408) 988-0639 


May 1993 


Windows/DOS Developer’s Journal — Page 25 



















































Figure 3 Adding a driver to the registry 


HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\Scsiscan 
DependOnGroup:REG_MULTI_SZ:SCSI mini port 
ErrorControl:REG_DWORD:Oxl 
Group:REG_REG_SZ:SCSI class 
Start:REG_OWORD:Oxl 
Type:REG_DW0R0:0x1 


Figure 4 Mapping the NT device name to the Win32 logical name 


HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Session Manager\DOS Devices 
SCANNER0:REG SZ:\Device\ScannerO 


The code disk also contains source files for a Win32 Con¬ 
sole program that does basically the same thing as test32. 
The Console interface allows you to write simple 32-bit char¬ 
acter-mode programs. Don't let the printfO statements and 
lack of UinMainf) fool you. This is a Win32 program and has 
no difficulty linking with and using hpscan32.dll. 

I have also placed on the code disk source files for a 16-bit 
program that performs reads, writes, and lOCTLs via the 
"HPSCAN" DOS device driver. If you plan to convert your 16-bit 
applications to the DOS device driver model, this may be a 
helpful example. Again, it performs the same three device 
commands as the previous two examples. Remember that for 


character-mode device drivers, you 
must set the device to raw (binary) 
mode after opening it, and you must 
use the DOS interrupt 21 function 44 to 
send IOCTL requests to a DOS device 
driver. 

Conclusion 

As you can see, if your interface 
protocol is already supported at the 
kernel-mode level by Windows NT (as 
SCSI, serial, and parallel are), supporting 
16-bit and 32-bit hardware-dependent 
applications under Windows NT is a fair¬ 
ly straightforward task. In the case of 
SCSI, even if your category of device re¬ 
quires you to write a new Class driver, 
at least you can take advantage of the lower-level Port and 
Miniport drivers provided by Windows NT. If you have an en¬ 
tirely different interface protocol, then your only option is to 
provide a complete (monolithic) kernel-mode driver, which is 
not nearly as straightforward. This is the realm of 
asynchronous I/O and “spin-locks.” 

Finally, let me stress again that the information presented 
here is based on preliminary versions of Microsoft's Win32 
software development tools and a preliminary version of the 
Windows NT environment Check the documentation carefully 
for changes with each subsequent prerelease build and the final 
release of Windows NT when available. 

The source code described here is 



At last! 

Pen Computing 

Without the Learning Curve 

Now, join hundreds of developers 
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try your hand at pen application development? Then 
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Device Drivers 


Self-Loading Device Drivers for DOS 

Tomas Nelson 

The introduction of installable device drivers in DOS 2.0 meant greatly increased 
flexibility for the control of peripheral devices. If you've ever tried to run a program 
that required the presence of a device driver, however, you know how inconvenient 
it can be to have to edit config.sys and reboot. A device driver capable of loading 
directly from the command line (or automatically from autoexec.bat) would offer a 
greater degree of freedom and convenience. This article explores one method of 
building a device driver with such capability. As a bonus, the technique described 
here permits a much easier way to test and debug device drivers. 

How DOS Loads a Device Driver 

The DOS BIOS module contains a number of resident device drivers that the 
bootstrap routine loads automatically during the boot sequence. Installable device 
drivers, however, must be specified in config.sys. Whatever their type, DOS places 
all drivers in a one-way linked list (chain) of device header blocks (see Listing 1). The 
first member of the list is always the NUL device, a sort of dummy device driver. To 
access character devices, DOS traverses the driver chain starting with the NUL device. 
This behavior means that you can supersede any default character driver by specify¬ 
ing a driver with the same name in config.sys. Your driver will appear before any 
of the default drivers in the chain, so DOS will encounter it first. 

DOS locates the driver chain immediately after a data area called the Configura¬ 
tion Variable Table (CVT), commonly known as the "List of Lists” (LOL) (see Figure 1). 
You can access the CVT by calling DOS function 52h, which returns a pointer to the 
CVT in ES:BX. The NUL device header is located immediately following (or in later 
versions, inside) the CVT. The makeup of this undocumented structure has changed 
to some extent with each release of DOS. While you can easily account for this 
variation in present code, the usual warnings apply regarding the use of undocu¬ 
mented features; namely, that these features are not guaranteed to be present in 
later DOS versions. 

After loading a driver specified in config.sys, DOS calls command code routine 0 
to initialize the driver before linking it into the driver chain. If it encounters problems 
during driver initialization, DOS abandons the attempt to load the current driver and 
proceeds to the next driver, if any, in config.sys. Figure 2 summarizes the data 
items DOS passes to the initialization routine (command code 0), as well as the items 
expected on return. Listing 1 outlines the structure of the request block, which is 
used to pass data to and from the driver command-code routines. 

As Figure 2 implies, loading a character device driver involves less labor than 
loading a block-type driver. Except for the status code, DOS expects only a break 
address on return from initializing a character driver. The break address tells DOS 
how much of the driver to keep in memory, and also where to load the next driver. 
DOS links a device driver into the driver chain by assigning the pointer field of the 
previous driver to point to the header of the new driver. If there are no other drivers 
to load, the pointer field of the header must contain -1L (Offffffffh ), which indi¬ 
cates the end of the chain. Once linked into the driver chain, you can access a 
character driver by calling DOS int 21h/3dh (DOS Open File). Using the returned 
handle, you can pass data to and from the device with DOS Read and Write func¬ 
tions ( 3fh and 40h, respectively), just as you would with a disk file. DOS accesses 
block-type drivers differently, since these drivers have no name in the header block. 


Tom Nelson is an independent consultant, author, and part-time artist. You can con¬ 
tact him at 5004 W. Mt. Hope Rd., Lansing, Ml 48917. 
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Figure 1 Structure of Configuration Variable Table 
(CVT) (“List of Lists") 


offsets 


Field 

Size 

V2 

V3.0 

V3.1+ 

Segment MCB Chain Head 

WORD 

-02h 

-02h 

-02h 

1st Drive Param Block 

DWORD 

OOh 

OOh 

OOh 

DCB List Head 

DWORD 

04h 

04h 

04h 

CLOCKS Device Header 

DWORD 

08h 

08h 

08h 

CON Device Header 

DWORD 

OCh 

OCh 

OCh 

# Logical Drives (1) 

BYTE 

lOh 

1 Bh 

21 h 

Max# BPS on Block Device 

WORD 

11h 

11 h 

lOh 

Ptr 1st Disk Buffer (2) 

DWORD 

13h 

13h 

12h 

Pointer CDS Table 

DWORD 

n/a 

17h 

I6h 

Pointer FCB Chain Head 

DWORD 

n/a 

22h 

1Ah 

#Protected FCBs 

WORD 

n/a 

26h 

1 Eh 

#Block Devices 

BYTE 

n/a 

lOh 

20h 

NUL Device Header Block 

12h 

17h 

28h 

22h 


Notes _ 

Offsets listed are relative to pointer returned in ES:BX by DOS 
int 21h/52h. 

MCB = Memory control block ("Arena Header”). 

DCB = Device Control Block or System File Table. 

BPS = Bytes per Sector. 

CDS = Current Directory Structure. 

FCB = File Control Block. 

(1) = LASTDRIVE under V3+. 

(2) = Points to disk buffer info under DOS 4+. 


Figure 2 Items passed in request block for driver 
command code 0 (initialize driver) 

Request Block on Input 

Offset 

Size 

Type 

Description 

02h 

BYTE 

Chr/Bl 

Command Code (0 = init) 

12h 

DWORD 

Chr/Bl 

Pointer to command line (1st 
byte after '=' in CONFIG.SYS line) 

16h 

BYTE 

Block 

1st available drive number 
(DOS 3+) 

17h 

BYTE 

Chr/Bl 

1 = Enable CONFIG.SYS error 
message 

0 = Disable CONFIG.SYS error 
message (4+) 

Request Block on Output 

Offset 

Size 

Type 

Description 

03h 

WORD 

Chr/Bl 

Status (OK = 0, Error = 8000h + 
code) 

ODh 

BYTE 

Block 

Number of units to be controlled 
by this driver 

OEh 

DWORD 

Chr/Bl 

Break Address (End of driver 
image) 

12h 

DWORD 

Block 

Pointer to array of pointers 
(offsets only) to BPB table(s). 

Array size = number of units 
controlled 


Loading and initializing a block driver involves more com¬ 
plex considerations. In addition to the command code and 
command-line address (the command line after the “=” in 
config.sys), DOS also passes the first free drive number to 
the driver's initialization routine (see Figure 2). This lets the 
block driver know what drive letter(s) DOS will assign to it. 
DOS appears to acquire this number by searching an array of 
structures, each element of which is a Current Directory struc¬ 
ture (CDS) (see Figure 3). Among other items, the CDS contains 
a drive:path string that specifies the current directory for a 
disk. The CDS array contains LASTDRIVE elements (default = 5), 
a quantity you can specify in config.sys. The CDS table also 
accounts for SUBSTe d and network-redirected drives. DOS uses 


Listing 1 sldd.inc 


LISTING 1 
sldd.inc 

Structure definitions and segment setup for 
self-loading MS-DOS device drivers. 


■.Driver command packet 
RH HDR struc 


rh_len 

db 

? 


rh_unit 

db 

7 


rh_cmd 

db 

7 


rh_status 

dw 

7 


rh_resrvd 

db 

8 dup(?) 


rh_nunits 

db 

7 

Iblock units to be supported 

rh_brkofs 

dw 

7 

load address for next 

rh_brkseg 

dw 

7 

... driver 

rh_bufofs 

dw 

7 

address of table of offsets 

rh_bufseg 

dw 

? 

...to BPB tables 

rh_drive 

db 

7 

1st free drive# (A=0, B=l) 


RH_HDR ends 

;Device driver header block . 

d_header struc 

d_next dd ? 

d_attr dw ? 

d_strat dw ? 

d_intr dw ? 

d_name db 8 dup(?) 

d_header ends 

; Specialized driver segment setup . 

NOWARN RES ;disable reserved-word warnings 



;for 1 

■CONST" and 

"STACK 1 

TEXT 

segment byte 

public 

'CODE' 

TEXT 

ends 



DATA 

segment word 

public 

'DATA' 

“data 

ends 



CONST 

segment word 

public 

'CONST' 

CONST 

ends 



BSS 

segment word 

public 

'BSS' 

BSS 

ends 



STACK 

segment para 

stack 

'STACK' 

STACK 

ends 



INIT 

segment word 

public 

'INIT' 

_I NIT 

ends 



WARN 

;re-enable all warnings 

; Establish SMALL model segment group . 

DGROUP 

group _DATA 

,C0NST,_BSS 

.STACK 


wptr 

equ 

<word ptr> 

bptr 

equ 

<byte ptr> 

dptr 

equ 

<dword ptr> 
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the index of the first free entry in the CDS table as the first 
available drive number, and passes it to the driver's initializa¬ 
tion routine. For example, if the first free drive is three (DO and 
the driver will control two units (devices), then the drive let¬ 
ters assigned to the drive will be D: and E:. Note that the CDS 
table does not exist under DOS 2.x. 

DOS requires that a block driver's initialization routine 
return, in addition to the break address, a pointer to an array 
of pointers to BIOS Parameter Blocks, as well as the size of the 
pointer array (see Figure 2). Since a single block driver can 
control more than one block device, the array of BPB pointers 
must contain 1 pointer for each device to be controlled. How¬ 
ever, there need not be a different BPB for each device; each 
element of the array may point to the same BPB if needed. 
Figure 4 outlines the structure of a BPB, which contains the 
physical characteristics of the block device(s) to be controlled. 

If the block driver was successfully initialized, DOS proceeds 
to update the CDS table and also builds a Drive Parameter 


Figure 3 Current Directory Structure (CDS) 


offsets 

Field 

Size 

V3 

V4,5 

Drive Designator and V 

WORD 

OOh 

OOh 

CWD (Path) String 

41 h 

02h 

02h 

Drive Status Bitmap 

WORD 

43h 

43h 

Pointer to DPB 

DWORD 

45h 

45h 

CWD 1st Cluster 

WORD 

49h 

49h 

Unknown 

DWORD 

4Bh 

4Bh 

Slash Offset in CWD 

WORD 

4Fh 

4Fh 

Unknown 

BYTE 

n/a 

51 h 

Ptr IFS Driver 

DWORD 

n/a 

52h 

Unknown 

WORD 

n/a 

56h 

Notes 

CDS does not exist under DOS V2. 




CWD = Current Working Directory. 



DPB = Disk (or Drive) Parameter Block. 



IFS = Installable File System 





Figure 4 Structure of BIOS parameter block and 
boot record extensions 


offsets 

Field 

Size 

V 2 

V3 

V4.5 

# Bytes per Sector 

WORD 

OOh 

OOh 

OOh 

#Sectors per Cluster 

BYTE 

02h 

02h 

02h 

#Reserved Sectors 

WORD 

03h 

03h 

03h 

Number of FATs 

BYTE 

05h 

05h 

05h 

Root Directory Size 

WORD 

06h 

06h 

06h 

Total Media Sectors (1) 

WORD 

08h 

08h 

08h 

Media Descriptor 

BYTE 

OAh 

OAh 

OAh 

#Sectors per FAT 

WORD 

OBh 

OBh 

OBh 

#Sectors per Track 

WORD 

n/a 

ODh 

ODh 

Number of Heads 

WORD 

n/a 

OFh 

OFh 

#Hidden Sectors 

DWORD 

n/a 

11 h 

11 h 

Reserved Area 

OBh 

n/a 

15h 

n/a 

Total Media Sectors (2) 

DWORD 

n/a 

n/a 

15h 

Reserved Area 

06h 

n/a 

n/a 

19h 

Notes 

FAT = File Allocation Table 

If (1) = 0, then (2) has total sector count 


Block (DPB, Figure 5) at the break address. DOS executes this 
procedure once for each device to be controlled by the driver. 
Besides duplicating information obtained from the BPB, the 
DPB contains a pointer to the header of the corresponding 


Figure 5 Structure of Drive Parameter Block 


offsets 

Field 

Size 

V 2 

V3 

V4+ 

Drive Number (A = 0) 

BYTE 

OOh 

OOh 

OOh 

Device Driver Unit# 

BYTE 

oih 

Oih 

Oih 

Bytes/Sector 

WORD 

02h 

02h 

02h 

(Sectors/Cluster) - 1 

BYTE 

04h 

04h 

04h 

Cluster Shift (1) 

BYTE 

05h 

05h 

05h 

1st FAT Sector 

WORD 

06h 

06h 

06h 

Copies of FAT 

BYTE 

08h 

08h 

08h 

Root Directory Entries 

WORD 

09h 

09h 

09h 

1st Data Sector 

WORD 

OBh 

OBh 

OBh 

Max Cluster + 1 

WORD 

ODh 

ODh 

ODh 

Sectors/FAT 

BYTE 

OFh 

OFh 

n/a 

Sectors/FAT 

WORD 

n/a 

n/a 

OFh 

1st Sector Root Dir 

WORD 

lOh 

lOh 

11 h 

Device Driver Header 

DWORD 

12h 

12h 

13h 

Media Descriptor 

BYTE 

16h 

16h 

17h 

Drive Access Flag 

BYTE 

I7h 

17h 

18h 

Pointer to Next DPB 

DWORD 

18h 

18h 

19h 

CWD 1st Cluster# 

WORD 

iCh 

n/a 

n/a 

CWD Path (ASCIIZ) 

40h 

1 Eh 

n/a 

n/a 

Last Allocated Cluster 

WORD 

n/a 

ICh 

1 Dh 

Number Free Clusters 

WORD 

n/a 

1 Eh 

1 Fh 

Notes 

FAT = File Allocation Table 

CWD = Current Working Directory 

Pointer to DPB returned in DS:BX by DOS int 21 h/32h, 
where DL = drive number (default = 0, A = 1). 

(1) = log 2 (sectors/cluster) 


Figure 6 Memory map of driver 


pspSeg 

CS:0000 


DS:0000 - 

(SEG DGROUP) 


SEGJNIT 


driver_end- 

(ifdef COMEXEC) 


Resident PSP block 


Device Header Block 

Resident Code 

strategyO: 

interrupt/): 


Resident Data 

(Includes CONST and 
_BSS segments) 


Resident Stack 


Setup Code and Data 
(Non-Resident) 


_TEXT Segment 


.DATA Segment 


STACK Segment 


JNIT Segment 
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Listing 2 

sldd.asm 







push 

dx 



LISTING 2 


push 

di 





push 

si 



Module: 

SLDD.ASM 

push 

bp 



Summary: 

Self-loading device driver 

push 

ds 



Assembler: 

TASM 2.0 

push 

es 



Author: 

T.W. Nelson 

pushf 




Version: 

1.00 

mov 

ax,seg DGROUP ;local data seg 


Date: 

29-Jan-1992 

mov 

ds.ax 



Notes: 


mov 

Caller ss.ss 




mov 

Caller sp.sp 


This module 

is "start-up" code and must 

cl i 




appear first in the link order. 

mov 

ss,ax 





mov 

sp,offset DGROUP:stack top 


Source code Copyright (c) 1992 T.W. Nelson. May 

sti 




be used only with appropriate acknowledgement of 

mov 

bp.sp 

;set C stack frame 


copyright. 


les 

di,[Rhdr] ;request header 




call 

exec command 




cli 


; restore CPU state 

INCLUDE sldd.inc 

mov 

ss,Caller ss ;and caller's stack 

ASSUME cs: TEXT,ds:DGR0UP,es:N0THING,ss:N0THING 

mov 

sp,Caller sp 

STACKSIZ equ 

256 ;driver stack size, words 

sti 






popf 




DATA segment 


pop 

es 


Rhdr dd 

? ;-> request header 

pop 

ds 


Caller ss dw 

? jcaller's stack vitals 

pop 

bp 


Caller sp dw 

? 

pop 

si 



psp dw 

? ;program seg prefix 

pop 

di 


public psp 


pop 

dx 



DATA ends 


pop 

CX 





pop 

bx 


STACK segment 


pop 

ax 



dw 

STACKSIZ dup(-l) interrupt stack 

ret 



stack_top dw 

? 

_interrupt endp 


public stack top 

TEXT ends 



STACK ends 






TEXT segment 


; Driver load and initialization code. The entire 




; INIT segment 

is jettisoned after initialization if 




; COMEXEC is not defined 



Resident driver header block. IMPORTANT: Header 





block must start at offset 0 in the TEXT segment. 

INIT segment 




otherwise offsets in 'drv strat' and 'drv intr' must 

ASSUME cs: INIT.ds: INIT,es:NOTHING,ss:NOTHING 


be corrected by subtracting (offset TEXT:drv header) 





from them. 


dosMajor dw 

0 

DOS version 1 s 




dosMinor dw 

0 


drv header label byte 

DosDataSeg dw 

0 

DOS data segment 

drv next dd 

-1 ;-> ground (NULL) 

ofsLoL dw 

0 

offset to DOS LoL 

drv attr dw 

8000h ;driver attributes 

pBlkDevCnt dd 

0 

-> Block device count in LoL 

drv strat dw 

strategy ;offset strategyQ 

LastDrive dw 

0 

LASTDRIVE value in LoL 

drv intr dw 

interrupt ‘.offset interrupt() 

ofsNULdev dw 

0 

offset of NUL device header 

drv name db 

"TEMPLATE",0 ;device name, 8 bytes 

pCDS dd 

0 

-> Current Directory Structure 




sizeofCDS dw 

0 

sizeof a CDS[] element 

public drv header, drv next, drv attr, drv strat 

pspSeg dw 

0 

PSP segment 

public drv intr 

drv name 

NULname db 

"NUL 

“,0 ;NUL device name 

extrn exec command:proc 

cmdPkt RH HDR <> 

driver command packet 




dw 

STACKSIZ dup(-l) jsetup stack 




setup stack dw 

? 


public strategy 







;Version-specific offsets for DOS data (CVT, etc.) ... 


strategy 

proc far 

D0S30 db 

10h,lBh,17h,28h,51h 


push 

ax 

D0S31 db 

20h,21h,16h,22h,51h 


push 

ds 

D0S4 db 

20h,21h,16h,22h,58h ;D0S 4+ 


mov 

ax,seg DGROUP 





mov 

ds.ax 

;byte offsets into initializer tables . 


mov 

wptr [Rhdr+2],es 

E pBlkDevCnt equ 0 



mov 

wptr [Rhdr],bx 

E LastDrive equ 1 



pop 

ds 

E pCDS equ 2 



pop 

ax 

E ofsNULdev equ 3 



ret 


E sizeofCDS equ 4 



strategy endp 







dos ver db 

“You need at least DOS ver 3",10,13,0 




bad dos db 

"Unknown 

DOS version",10,13,0 

public interrupt 

no nul db 

“Can't find NUL device header",10,13,0 




is loaded db 

“ device 

is already loaded",10,13,0 


interrupt 

proc far 

is file db 

" device 

is a disk file”,10,13,0 


push 

ax ;Save caller's CPU state 

bad init db 

“Driver initialization failed",10,13,0 


push 

bx ;and stack context .... 

unloaded db 

"Driver template unloaded",10,13,0 


push 

cx 

CDSfull db 

“Out of CDS entries",10,13,0 
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block driver. DOS also places all DPBs in a one-way linked list. 
A pointer to the head of the DPB list is contained in the CVT. 
You can locate the DPB for a specified drive by calling int 
21h/32h with DL containing the drive number (default = 0, A = 
1, etc). The function returns a pointer to the drive’s DPB table 
in DS:BX. To build the DPB, DOS must translate and update 


Listing 2 continued 

no_block 

db "Can't 

install block device",10,13,0 


Current Directory Structure . 

CDS struc 



path db 

43h dup(?) 

;current path 

flags dw 

? 

0 if entry available 

pDPB dd 

? 

;-> disk param block 

sclust dw 

? 

;starting cluster 

ffff dd 

? 

;always -1 (?) 

slash dw 

? 

;ofs 'V in current path 

qmarkl db 

? 

;unknown byte (DOS 4+) 

ifs dd 

7 

;-> ? (DOS 4+) 

qmark2 dw 

7 

;unknown byte (DOS 4+) 

CDS ends 



IFDEF COMEXEC ;load command shell to simulate 



;residency 

comSpec 

db 

"c:\command.com",0 

exec params 

equ 

$ ;parameter block for 

environ seg 

dw 

? ;DOS EXEC function .... 

command ofs 

dw 

7 

command seg 

dw 

7 

fcbl ofs 

dw 

? 

fcbl seg 

dw 

7 

fcb2 ofs 

dw 

7 

fcb2 seg 

dw 

7 

save_sp 

dw 

7 

ENDIE ;COMEXEC 



entry: 

al == exit 

code 


exit: 

n/a 



•xit2dos: 




mov 

ah,4ch 

;DOS exit 


int 

21h 



entry: 

ds:bx - asciiz message string 


exit: 

n/a 



■rr exit: 




cal 1 

putstr 



mov 

al ,3 



jmp 

exit2dos 



entry: 

ds:bx - asciiz message string 


exit: 

n/a 



jutstr proc near 



push 

ax 



push 

bx 


putstrl: 




mov 

al,[bx] 



or 

al.al 

;finished? 


jz 

PX 

;yes 


mov 

ah.Oeh 

;BIOS write tty 


push 

bx 

;save it 


xor 

bx.bx 

;page 0 


int 

lOh 



pop 

bx 

;restore bx 


inc 

bx 

;increment pointer 


jmp 

putstrl 

;next byte 


px: 




pop 

bx 



pop 

ax 



ret 



putstr endp 
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Listing 2 continued 


; entry: n/a 

; exit: ax = index of 1st avail CDS entry, aborts 

; program if no free entries exist 

; note: pCDS, sizeofCDS must be known before call 

new_drive proc near 


push 

es 


push 

bx 


les 

bx.pCDS 

;point to table head 

mov 

ax,0 

;index of 1st CDS entry 

cmp 

es:[bx].flags.O 

;entry available? 

je 

nex 

;yes, quit 

add 

bx,sizeofCDS 

;else, -> next entry 


information from the BPB into runtime DPB format. You have 
access to this same procedure by calling int 21h/53h. To use 
this function, load DS:SI with the address of a BPB table 
(returned by the driver in the request block) and point ES:BP 
to the area that will contain the new DPB. The function does 
not appear to return an indication of error in the carry flag. 

Designing a Self-Loading Device Driver 

To construct a driver with self-loading capabilities, you 
have to imitate what DOS does within the context of a normal 
.com or .exe format file. The result is a hybrid program that 
combines features of device drivers and TSRs, giving you the 
best of both worlds. On the one hand, a TSR-like device driver 
offers many advantages in flexibility (which I describe fully 
later.) On the other, a driver-like TSR 
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1-800-336-1961 

1-203-489-5335 voice 1-203-489-5746 fax 
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that employs some of the well-docu¬ 
mented features of DOS is easier to live 
with. Coding a TSR this way helps to 
avoid some of the problems that arise 
from lack of standardization of TSRs. 

You can think of the self-loading 
code as a shell that surrounds the resi¬ 
dent driver code. The shell exists only 
to initialize the driver and place it in the 
proper perspective so that DOS knows 
where to look for it. Once finished with 
its work, the shell drops away. Listing 2 
(sldd.asm) presents a self-loading driver 
shell that implements this strategy. Be¬ 
cause this module contains the special¬ 
ized start-up code that performs the re¬ 
quired initialization tasks, it must ap¬ 
pear first in the link order. Listing 2 also 
contains the device header and entry 
points for the strategy and interrupt 
routines. 

The resident portion of the driver 
follows standard Microsoft/Borland con¬ 
ventions for naming and ordering seg¬ 
ments. The resident driver code thus 
exists within the framework of a normal 
.exe format program. This means that 
you can use C or another suitable high- 
level language to write the unique parts 
of the driver, then you simply link it 
with the boilerplate code presented 
here. Listing 1 ( sldd.inc ) contains the 
segment definitions used by the driver. 

The segments defined in Listing 1 in¬ 
clude a special segment named INIT, 
which falls after all other segments. This 
segment contains code that initializes 
the resident portion of the driver code 
in a manner similar to many TSRs. The 
_INIT segment is designed to jettison 
itself once setup has been completed. 
Although you load the driver as an . exe 
program, the code within _INIT acts as 
a separate . corn-format program tacked on 
to the end of the main resident program. 
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All data and code occur in a single seg¬ 
ment, so both CS and DS are normally 
ASSUMEd relative to the _INIT segment 
throughout the start-up procedure. The 
only exception occurs when the start¬ 
up code must refer to data in the resi¬ 
dent segments. 

Figure 6 displays a memory map of 
the driver. Since a self-loading device 
driver has to be loaded as either a . com 
or (in this case) an .exe file, the in¬ 
stalled driver will be prefaced by a Pro¬ 
gram Segment Prefix (PSP) block, 256 
bytes long. It should be possible to re¬ 
use most of this block as buffer space 
or for data storage at runtime, but I am 
unsure about the correctness of treat¬ 
ing the entire PSP in this manner. At a 
minimum, you should be able to re-use 
the 128-byte command tail at 
PSP:0080h without reservation once 
setup has been completed. If your resi¬ 
dent code uses open files, however, 
you will need to preserve the area 
beginning at PSP:0018h, which contains 
the file handle table and other sensitive 
items. 

The driver’s resident code and data 
immediately follow the PSP in a group¬ 
ing of standard segments. This segment 
arrangement allows you to link with 
modules coded in an appropriate high- 
level language. However, an important 
exception to standard .exe usage ap¬ 
pears in Listing 2. The driver’s header 
block (see Listing 1) must occur in the 
same segment (_ TEXT) as the 
strategy() and interrupt() routines 
because the header contains only of¬ 
fsets to these routines, not full seg- 
menboffset (far) pointers. Also note 
that the header block must normally 
occur at offset 0 in the _TEXT seg¬ 
ment. The assembler calculates offsets 
to strategy() and interrupt() rela¬ 
tive to the start of the _TEXT segment. 
If you place the header at a non-zero 
offset within _TEXT, you must correct 
the offsets to both strategy() and in¬ 
terrupt () by a corresponding amount. 
Otherwise, a caller will not be able to 
find them, since it must assume the 
header block starts at offset 0. 

If you code part of your driver in a 
high-level language, uninitialized data 
will be placed in the _BSS segment. One 
function of a compiler’s normal start-up 
code is to initialize this data to NULL. Al¬ 
though the same method could be em¬ 


bodied in the start-up code in Listing 2, 
I have not done so. Unless you make 
provision for this, make sure all your 
data is initialized before use or that you 
write code without assuming pre-initial- 
ized NULL data. Also, you must ensure 
that your compiler enforces byte-pack¬ 
ing of structures. 

Linking outside library code to your 
driver can also be problematic since 
some of this code depends on data ini¬ 
tialized during normal start-up. This is 
particularly true of functions like mal- 
loc() or print/() that assume the 
presence of a heap. Although you could 
allocate space for a heap in a self-load¬ 
ing driver, you would also have to 
supply special versions of malloc(), etc. 
So unless you’re using simple routines 
like strlen(), you should generally 
plan on coding your own versions of 
standard library routines. 

Although not strictly necessary, a 
resident STACK segment makes life 
easier, especially if you're working with 
a stack-intensive, high-level language 
such as C. Running your device driver 
from the caller’s stack (usually the DOS 
kernel) places unnecessary restrictions 
on your code (the DOS stack is repor¬ 
tedly as short as 50-60 bytes). A resi¬ 
dent stack contributes to your peace of 
mind and lets you work with automatic, 
stack-based variables instead of using 
global data exclusively. This arrange¬ 
ment also allows you to compile your 
high-level code assuming SS == DS (the 
default for C). If you use high-level code, 
make sure you disable stack probing, 
which some compilers insert by default. 
I haven’t included a way to implement 
stack probing in the driver, but you 
could probably arrange this without 
much trouble. 

DOS will also create a process en¬ 
vironment block when it loads the 
driver. Your program may need to refer 
to the environment block during setup. 
The environment occurs within a 
separate segment and may safely be 
deallocated after start-up is completed. 
Since the DOS kernel handles all 
memory allocation/deallocation on be¬ 
half of client programs, you simply 
release the environment and hand it 
back to DOS. DOS will re-use the same 
space for (probably) the next program’s 
environment block. 
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Listing 2 continued 

inc 

ax 

;next index 

xor 

bx.bx 

n5: cmp 

ax.LastDrive 

;end of loop? 

mov 

bl.al 

jl 

nl 

;no, continue 

mov 

dosMajor.bx 

mov 

bx,offset CDSfull ;yes, no entries free 

mov 

bl .ah 

jrnp 

err exit 

;abort the program 

mov 

dosMinor.bx 

nex: pop 

bx 




pop 

es 


* 

Grab data from CVT (List of Lists) - 

ret 



mov 

ah,52h 

new drive 

endp 


int 

21h ;es:bx -> LoL 




cmp 

dosMajor,3 

• - 



ja 

dos 4x 

start up: 



cmp 

dosMinor.O 




ja 

dos 31 

mov 

ax.cs 

;Recover segment 

mov 

di.offset D0S30 

mov 

ds.ax 

jregisters and PSP seg 

jmp 

short go CVT 

mov 

pspSeg.es 


dos 31: 


cli 



mov 

di.offset DOS31 

mov 

ss.ax 


jmp 

short go CVT 

mov 

sp,offset setup stack 

dos 4x: 


sti 



mov 

di .offset D0S4 

mov 

ax.seg DGR0UP 


cmp 

dosMajor,5 

mov 

ds.ax 


jbe 

go CVT 

ASSUME 

ds:DGR0UP 

;get -> PSP for 

mov 

bx,offset bad dos 

mov 

psp.es 

jresident portion 

jmp 

err exit 

push 

cs 


go CVT: 


pop 

ds 


mov 

DosDataSeg.es 

ASSUME 

ds: INIT 


mov 

ofsLoL.bx 




xor 

ax,ax 

; - Check and save DOS version - 

mov 

al,[di].E pBlkDevCnt 

mov 

ax,3000h 

;D0S get version 

add 

ax.bx 

int 

21h 


mov 

wptr pBlkDevCnt[2],es 

cmp 

al ,3 

;at least ver 3? 

mov 

wptr pBlkDevCnt[0],ax 

jge 

saveDOSver 

;yes, bypass 

xor 

ax,ax 

mov 

bx,offset dos ver 

;no .... 

mov 

al,[di].E LastDrive 

jmp 

err exit 

;quit 

mov 

si ,ax 

saveDOSver: 



mov 

al,bptr es: [bx+si] 
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Loading and Initializing the Driver 

As Listing 2 shows, the driver starts execution at the loca¬ 
tion labeled start_up in th e_INIT segment, start up begins 
by loading segment registers with appropriate values and 
saving a pointer to the PSP segment. It also sets SS:SP to use 
a separate stack area within the _INIT segment to avoid con¬ 
flict with the resident stack. Later, start_up will have to call 


the resident interrupt () routine, which uses the resident 
stack. The code also checks the DOS version. You will notice 
that I've restricted the code to DOS 3 or higher for simplicity; 
you could add code for DOS 2.x without a great deal of 
trouble. 

start_up then proceeds to access several variables from 
the CVT. start up also uses the CVT to locate the head of the 
driver chain, which begins with the NUL device header block. 


Listing 2 continued 

mov 

LastDrive,ax 


mov 


bx,offset cmdPkt ;es:bx -> cmd pkt 

xor 

ax,ax 


call 


far ptr strategy 

mov 

al,[di].E pCDS 


call 


far ptr interrupt 

mov 

si ,ax 


test 


cmdPkt.rh status,8000h ;error? 

mov 

ax.wptr es:[bx+si] 

;-> ofsCDS 

jz 


init block ;no, continue 

mov 

wptr pCDS[0],ax 


mov 


bx,offset bad init ;yes, bail out 

mov 

ax.wptr es:[bx+si+2] 

;-> segCDS 

jmp 


err exit 

mov 

wptr pCDS[2],ax 


init block: 


xor 

ax,ax 


include 

initblk.asm ;init block device 

mov 

al.Tdi1.E ofsNULdev 





add 

ax,bx 


;- 

Patch driver into existing chain - 

mov 

ofsNULdev,ax 


push 


ds 

xor 

ax, ax 


mov 


es.DosDataSeg 

mov 

al,[di].E sizeofCDS 


mov 


bx,ofsNULdev 

mov 

sizeofCDS.ax 


mov 


ax.seg TEXT 




mov 


ds.ax 

; - Verify that NUL device is present - 

ASSUME 

ds: TEXT 

mov 

si,offset NULname 

;ds:si 

mov 


dx,wptr es:[bx+2] ;dx:ax ** next driver 

mov 

di.ofsNULdev 

;es:di -> device hdr 

mov 


ax.wptr es:[bx+0] ;after NUL device. 

add 

di,d name 

;-> device name 

mov 


wptr drv next[0],ax ;make ours point to 

mov 

cx,8 

;compare count 

mov 


wptr drv next[2],dx ;what NUL pointed to. 

repz 

cmpsb 

;get 1st non-match 

mov 


wptr es:[bx+O].offset TEXT:drv header 

jz 

chk load 

;NUL device present 

mov 


wptr es:[bx+2],ds ;point NUL to us 

mov 

bx,offset no nul 

;can't find NUL 

pop 


ds 

jmp 

err_exit 


ASSUME 

ds:_INIT 

; - Check driver load status 


IFNOEF 

COMEXEC ;release environment 

chk load: 



mov 


es.pspSeg ;get environ seg 

mov 

ax,seg TEXT 


mov 


es,es:[2ch] ;in PSP block 

mov 

ds,ax 


mov 


ah,49h ;DOS free memory 

mov 

dx.offset TEXT:drv 

name ;ds:dx = our name 

int 


21h 

mov 

ax,3d00h 

;D0S Open File, rdonly 

ENDIF 



int 

21h 





jc 

init driver 

;0K, driver not loaded 

» 

Compute resident program size - 

mov 

bx.dx 

;not OK, 

mov 


dx,cmdPkt.rh brkofs 

call 

putstr 

;print device name 

mov 


cx,4 

push 

cs 


shr 


dx.cl 

pop 

ds 

;fix ds 

inc 


dx 

mov 

bx.ax 

;bx - open handle 

add 


dx,cmdPkt.rh brkseg 

mov 

ax,4400h 

;DOS IOCTL, 

sub 


dx.pspSeg president paragraphs 

int 

21h 

;get device info 




test 

dx.0080h 

;is it a file? 

IFDEF 

COMEXEC 

jnz 

already loaded 

;no, driver installed 

t 

Load Command.com to simulate residency - 

mov 

bx,offset is_file 

;yes, file w/ same name 

mov 


es.pspSeg ;beg segment address 

jmp 

err exit 

;qui t 

mov 


bx.dx ;total resident size 

already loaded: 


mov 


ax,4a00h ;DOS SETBLOCK 

mov 

bx,offset is loaded 

;and loaded msg 

int 


21h ;return unused memory 

jmp 

err exit 

;quit 

mov 


di,0080h ;es:di -> command line 




mov 


bptr es:[di],0 ;cmd length » zero 

; - Build cmd packet and initialize driver - 

mov 


dx,offset comSpec 

init_driver: 


mov 


cx.es:[2ch] ;grab environment seg 

push 

CS 


mov 


environ seg.cx 

pop 

ds 

;fix ds 

mov 


command ofs.di 

mov 

cmdPkt.rh cmd,0 

;driver INIT command 

mov 


command seg.es 

mov 

cmdPkt.rh len.size RH HDR 

mov 


fcbl ofs,5ch 

mov 

cmdPkt.rh unit.O 


mov 


fcbl seg.es 

mov 

es.pspSeg 


mov 


fcb2 ofs,6ch 

mov 

di,81h 

;es:di -> PSP cmd line 

mov 


fcb2 seg.es 

dl: cmp 

bptr es:[di],' ' 


mov 


ax,4b00h ;DOS EXEC program 

jne 

d2 

'.skip leading spaces 

mov 


save sp.sp 

inc 

di 


push 

cs 

jmp 

dl 


pop 


es 

d2: mov 

cmdPkt.rh bufofs.di 


mov 


bx,offset exec params 

mov 

cmdPkt.rh bufseg.es 


int 


21h ;load COMMAND.COM 

call 

new drive 

;don't know yet if 

mov 


ax,cs jrestore regs 

mov 

cmdPkt.rh drive,al 

jit's a block device 

mov 


es.ax 

push 

CS 


mov 


ds.ax 

pop 

es 


di 
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Listing 2 continued 

mov 

ss,ax 


mov 

sp.save sp 


sti 



; - Remove driver from device chain - 

push 

ds 


mov 

es.DosDataSeg 

;point to NUL device 

mov 

bx.ofsNULdev 


mov 

ax.seg TEXT 


mov 

ds.ax 


ASSUME 

ds: TEXT 


mov 

ax.wptr drv next[0] 

;dx:ax = what 

mov 

dx.wptr drv next[2] 

;we point to 

mov 

wptr es:[bx+0],ax 

-.make NUL device point 

mov 

wptr es:[bx+2],dx 

;to it instead 

pop 

ds 


ASSUME 

ds: INIT 


mov 

bx,offset unloaded 


call 

putstr 

print unloaded msg 

xor 

ax, ax 

;D0S exit code 

jmp 

exit2dos 

;quit, back to DOS 

driver end 

label byte 

;end of C0MEXEC image 

public driver_end 


ELSE 


;true residency 

mov 

ax,3100h 

;DOS TSR 

int 

21 h 


ENDIF ;C0MEXEC 


INIT 

ends 



end start up 


;— End of 

File- 
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□ Request 104 on Reader Service Card □ 


Since the CVT varies in structure depending on the DOS ver¬ 
sion, I used a series of version-specific setup tables to insulate 
the code from most of this variability. The setup tables con¬ 
tain offsets into the CVT, as well as the size of the CDS. 
start up points register DI to the correct setup table based 
on the DOS version. start_up can then unpack the correct 
item from the setup table without further regard to the DOS 
version. If the structure of the CVT changes in future versions 
of DOS, you can easily update the setup tables. 

To verily that it has found the head of the driver chain, 
start_up compares the presumed location of NUL with the 
known name of the NUL device. The program aborts immediately 


Listing 3 cmd.asm 


LISTING 3 


Module: 

Summary: 

Assembler: 

Author: 

Version: 

Date: 

Notes: 


CMD.ASM 

Route driver interrupt call to command 
code routine 
TASM 2.0 
T.W. Nelson 
1.00 

29-Jan-1992 


Source code Copyright (c) 1992 T.W. Nelson. May 
be used only with appropriate acknowledgement of 
copyright. 


INCLUDE sldd.inc 

ASSUME cs:_TEXT,ds:DGROUP,es:NOTHING,ss: NOTHING 
_DATA segment 

logon db “Self-loading Device Driver,",10,13 

db “(Template) Version 1.00",10,13,10,13,'$' 


Dispatch table for command-code routines 


cmdTab 

equ $ 

dw 

init 

dw 

media_check 

dw 

build_bpb 

dw 

ioctl_read 

dw 

device_read 

dw 

nd_read 

dw 

input_status 

dw 

input_flush 

dw 

device_write 

dw 

verify_write 

dw 

output_status 

dw 

output_flush 

dw 

ioctl_write 

dw 

device_open 

dw 

device_close 

dw 

rem_media 

dw 

output_busy 

dw 

bad_command 

dw 

bad_command 

dw 

generic_ioctl 

dw 

bad_command 

dw 

bad_command 

dw 

bad_command 

dw 

get_logdev 

dw 

set_logdev 


0 = initialize driver 
1 

2 * build BIOS param block 

3 - read io control data 

4 

5 * non-destructive read 

6 

7 * flush input buffers 

8 

9 = write with verify 

10 

11 = flush output buffers 

12 - write io control data 

13 (DOS 3+) 

14 (DOS 3+) 

15 - removable media (3+) 

16 * output until busy (3+) 

17 = not used 

18 - not used 

19 = generic io control (3.2+) 

20 « not used 

21 = not used 

22 = not used 

23 - get logical device (3.2+) 

24 - set logical device (3.2+) 


;uummy uru ror testing diock ariver setup 
bpbstruc equ $ 

dw 512 ;bytes/sector 

db 2 ;sectors/cluster 

dw 1 ;reserved sectors 
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if a match is not found. The driver must also guard against 
repeated invocations of itself. Since the driver eventually links 
itself into the driver chain, you can let DOS check for the 
presence of an earlier invocation by issuing an Open 
File/Device call ( int 21h/3dh). This function also provides 
application programs with a well-documented method of 
determining the load status of any driver/TSR that links itself 
into the driver chain. You use int 21h/3dh for this purpose 
exactly as you would when opening a disk file. Be sure to set 
the open mode in AL to read only (AL = 0). If the carry flag is 
set on return, the device has not been installed yet. If the 


carry flag is clear, either the device is installed or a disk file 
exists with the same name as your device. 

start_up must then call the driver's interrupt() routine 
(also in Listing 2) to initialize the driver, exactly as DOS would 
do. It fills a request header block (cmdPkt) with appropriate 
values and first calls strategyf), which simply saves a pointer 
to cmdPkt. Immediately after, start_up calls interrupt() to 
perform the actual initialization. To fill the request header 
block, startjup must also call new_drive() to get the next 
available drive number. Although this item concerns only 
block-type drivers, start_up fills cmdPkt.rh_drive with the 
value returned by new_drive(), regardless of the type of 


Listing 3 

continued 



db 

2 

;#fat tables 

ELSE 


dw 

112 

;#directory entries 

mov es:[di].rh brkofs.O 


dw 

720 

;#logical sectors 

ENDIF 


db 

Ofdh 

;media descriptor byte 



dw 

2 

;#fat sectors 

; - return items for block driver - 


dw 

9 

; sectors/track 

mov es:[di].rh nunits,2 


dw 

2 

;#sides 

mov es:[di].rh bufofs,offset DATA:bpbtab 


dw 

0 

;hidden sectors 

mov es:[di].rh_bufseg,seg _DATA 

bpbtab 

dw bpbstruc ;two units, same table 

; - display log on message - 



dw bpbstruc 

mov dx,offset logon 





mov ah,09h ;D0S display '$' string 


DATA 

ends 


int 21h 





xor ax,ax ;no error 

IFDEF 

COMEXEC 


ret 


INIT 

segment 



extrn 

driver end:byte 

media check: ;1 


INIT 

ends 


build bpb: ;2 * build BIOS param block 

ENDIF 

: COMEXEC 

ioctl read: ;3 - read io control data 





device read: ;4 


TEXT 

segment 


nd read: ;5 » non-destructive read 





input_status: ;6 

inputflush: ;7 * flush input buffers 

xor ax,ax ;return 'no error' status 


Set up call to conmand code routine. On entry. 


es:di 

points to the request header. Returns 

ret 


result code in request header status word. 

device write: ;8 





verify write: ;9 - write with verify 

public 

exec command 

mov cx,es:[di+18] ;byte count 





les di,es:[di+14] ;xfer address 

exec command 

proc near 

jcxz w2 ;check for runaway error 



push 

es -.save req hdr 

wl: 



push 

di 

mov al.es:[di] 



xor 

bx.bx 

mov ah.Oeh -.BIOS write tty 



mov 

bl,es:[di].rh cmd ;load cmd code 

xor bx.bx ;page 0 



cmp 

bx,24 ;legal? 

int lOh 



jle 

execl ;yes, continue 

inc di ;increment pointer 



call 

bad command ;set error code 

loop wl ;next byte 



jmp 

short exec2 ;bypass call 

w2: 

execl: 






shl 

bx,l ;cmdTab index 

output status: ;10 



call 

wptr [bx].cmdTab ;to cmd routine 

output flush: ;11 = flush output buffers 

exec2: 


ioctl write: ;12 * write io control data 



pop 

di ; restore req 

device open: ;13 (DOS 3+) 



pop 

es jheader 

device close: ;14 (DOS 3+) 



or 

ax,0100h ;set 'done' bit 

rem media: ;15 * removable media (3+) 



mov 

es:[di].rh status,ax ;assign status 

output busy: ;16 » output until busy (3+) 



ret 


generic ioctl: ;19 = generic io control (3.2+) 

exec command 

endp 

get logdev: ;23 = get logical device (3.2+) 





set_logdev: ;24 * set logical device (3.2+) 

xor ax,ax ;return 'no error' status 

ret 


Command code 

routines. On entry, es:di points to the 


caller's request header. Each routine must return 

bad command: 


status in ax: 

0 if successful or (8000h + error code) 

mov ax,8003h 


if function ended in error. 

ret 


nit: 


;0 - initialize driver 

TEXT ends 





end 



return 

break address - 



mov 

es: 

[di].rh brkseg.seg INIT 

End of file - 


IFDEF COMEXEC 



mov 

es: 

[di],rh_brkofs,offset _INIT:driver_end 
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driver to be loaded. If interruptf) 
returns an error code, start_up imme¬ 
diately aborts the program. 

The driver interruptf) routine for 
the most part follows standard proce¬ 
dure. As noted earlier, it sets SS:SP to 
point to the resident stack. It also 
points ES:DI to the request packet and 
then calls exec_command(), found in 
and. asm (Listing 3). exec_command() 
routes the call to the correct command 
code routine. It uses the command 


code as an index into a jump table. 
exec_command() calls each command 
code routine with ES-.DI pointing to the 
request packet. It also expects each 
routine to return a status code in AX, 
which will be 0 if no errors were en¬ 
countered. 

Standard device drivers loaded from 
config.sys are restricted to DOS int 
21h functions Olh-Och and 30h during 
execution of the init() routine. How¬ 
ever, the init() routine in Listing 3 is 


not subject to these restrictions. The 
self-loading capability allows you to ex¬ 
ecute any DOS function inside init(). 
Moreover, instead of imitating DOS by 
calling initf) via the standard 
strategy() and interruptf) entry 
points, you could place initf) within 
the _INIT segment. This would allow 
initf) to drop away with the _INIT 
segment when the driver goes resident, 
which may be important if you have 
lengthy initialization code. On the other 


Listing 4 initbik.asm 


LISTING 4 

Module: 

Summary: 

Assembler: 

Author: 

Version: 

Date: 

Notes: 


initbik.asm 

Setup data structures for block device 
Include file for sldd.asm module 
TASM 2.0 
T.W. Nelson 
1.00 

29-Jan-1992 


Source code Copyright (c) 1992 T.W. Nelson. May 
be used only with appropriate acknowledgement of 
copyright. 


mov 

mov 

test 

jz 

jmp 

initO: 

cmp 

jne 

mov 

jmp 

initl: 

cmp 

je 

mov 

mov 

shr 

inc 


ax.seg TEXT 
es.ax 

es:drv_attr,8000h 

initO 

init x 


;block device? 
;yes, continue 
;else bypass 


cmdPkt.rh_nunits,0 ;any units returned? 
initl ;yes, continue 

bx,offset no_block ;no, abort 
err exit 


cmdPkt.rh_brkofs,0 

init2 


;paragraph aligned? 
;yes, bypass 


bx,cmdPkt.rh_brkofs ;no, align on pgraph 

cx,4 

bx.cl 

bx 


add 

cmdPkt.rh_brkseg,bx 


mov 

es,cmdPkt.rh_brkseg 

mov 

cmdPkt.rh_brkofs,0 


mov 

bx,0 ;-> new DPB 

t2: 



pop 

ax jrecover new drive# 

xor 

cx.cx 

;starting unit# 

mov 

es:[bx],al 

jmp 

initlO 

;test loop exit 

pop 

cx ;recover unit# 

t3: 



mov 

es:[bx+1],cl 

call 

new_drive 

;get next CDS entry 

inc 

cx ;next unit# 

push 

ax 

;save result 

cmp 

dosMajor,3 

les 

bx.pBlkDevCnt 


jle 

init6 

inc 

bptr es:[bx] 

;1 more block device 

inc 

bx ;adjust for DOS 4+ 

mov 

ah,32h 

;D0S get DPB pointer 

init6: 


mov 

dl.al 

;drive# (A=l,B=2,etc.) 

mov 

wptr es:[bx+12h].offset _TEXT:drv_header 

int 

21h 

•.return ds:bx -> DPB 

mov 

wptr es:[bx+14h],seg _TEXT 

push 

ds 


mov 

wptr es:[bx+18h].Offffh ;set end of DPB 

pop 

es 

;es:bx -> last DPB 

mov 

wptr es: [bx+lah] .Offffh -.chain 

mov 

ax.seg _INIT 


add 

cmdPkt.rh_brkseg,2 ;2 pgraphs for DPB 

mov 

ds.ax 

;fix ds 

add 

cmdPkt.rh_bufofs,2 ;-> next BPB 

add 

bx.24 

;-> DPB link field 

initlO: 


cmp 

dosMajor,3 


cmp 

cmdPkt.rh_nunits,0 ;more block units? 

jle 

init4 


je 

init_x ;no, quit 

inc 

bx 

;adjust for DOS 4+ 

dec 

cmdPkt.rh_nunits ;yes, continue 

t4: 



push 

cx ;save unit# 

push 

es 


jmp 

i ni t3 

push 

bx 

-.save -> DPB link 

init_x: 



mov es,cmdPkt.rh_bufseg 

mov bx,cmdPkt.rh_bufofs ;es:bx -> BPB offset 

mov si,es:[bx] ;unpack -> BPB 


push es 

mov es,cmdPkt.rh_brkseg 

mov bp,0 

pop ds 

mov ah,53h 

int 21h 

mov ax.seg _INIT 

mov ds,ax 

pop bx 

pop es 

mov ax,cmdPkt.rh_brkseg 

mov wptr es:[bx+0],0 

mov wptr es:[bx+2],ax 

pop ax 

push ax 

mov bx.sizeofCDS 

mul bl 

les bx.pCDS 

add bx.ax 

mov wptr es:[bx].flags,1 shl 14 

mov ax,cmdPkt.rh_brkseg 

mov wptr es:[bx].pDPB[0].0 

mov wptr es:[bx].pDPB[2],ax 

mov es:[bx]-sclust.Offffh 

mov wptr es:[bx].ffff[0].Offffh 

mov wptr es:[bx].ffff[2].Offffh 

mov es: [bx].slash,2 

cmp dosMajor,3 

jle init5 

mov es:[bx].qmarkl.O 

mov es: [bx].qmark2,0 

mov wptr es:[bx].ifs[0],0 

mov wptr es:[bx].ifs[2],0 

init5: initialize new DPB 


;es:bp * new DPB addr 

;ds:si -> BPB 

;D0S xlat BPB -> DPB 


;fix ds 

;recover -> DPB link 

;1ink offset 
;link segment 
;recover new drive# 
;save again 


;-> new CDS entry 


;-lL 


initialize 
;D0S 4+ entries 


End of file 
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hand, keeping init() in its normal 
place makes it easier to convert the 
driver back to a standard format (one 
loaded from config.sys). This might be 
the better choice if you're using the 
self-loading method for its enhanced 
debugging facility and intend to convert 
to standard format later. 

The code in Listing 3 contains no 
provision for calling command code 
routines written in a high-level lan¬ 
guage, but you can implement this 
easily with a few minor modifications. 
First, replace the function names in the 
jump table (cmdTab) with command 
code routines you've defined in a high- 
level module. Then, to allow your 
routines access to the request header 
block, pass them a {far) pointer to it in 
exec_command(): 

push es ;request block segment 

push di {request block offset 

call word ptr [bx].cmdTab ;cal 1 
routine 

add sp,4 {adjust stack (C functions) 

Alternatively, you could assign ES:DI to 
a pointer object, one that your high- 
level routines could access globally. As 
before, each of the command code 
routines must return a status code 
(usually in AX). 

The code in Listing 4 (initblk.asm) 
handles the special initialization require¬ 
ments of block-type device drivers. 
Designed as an include file, this module 
is inserted at the appropriate point in 
start_up and can be left out if you're 
building a character-type driver. For the 
most part, it follows a procedure very 
similar to that outlined earlier for DOS. 
its major task is to build a Disk 
Parameter Block (Figure 5) immediately 
after the driver image in memory. It 
builds one DPB table for each unit to be 
controlled by the driver. It must also 
update the CDS array (Figure 3) and the 
block device count in the CVT (Figure 1). 

When start_up safely completes all 
initializations, it inserts the new driver 
into the driver chain immediately after 
the NUL device. start_up must also 
compute the size of the resident por¬ 
tion of the driver on the basis of the 
returned break address and any 
modifications made to the break ad¬ 
dress in initblk.asm (Listing 4). The 
total resident size is expressed in terms 


of paragraphs (1 paragraph = 16 bytes). 
start_up then completes the installa¬ 
tion by calling the DOS Keep (TSR) func¬ 
tion, int 21h/31h, where DX contains 
the number of resident paragraphs. At 
this point, the driver is installed in 
memory and will function as a normal 
device driver, at least from DOS's 
perspective. 

Debugging and Testing 
the Driver 

The difficulties involved in debugging 
a standard device driver that DOS loads 
from config.sys are well known and 
undoubtedly contribute to the general 
perception of drivers as being “difficult.” 
A software-only debugger used in the 
conventional manner usually won’t 
work. Remote debugging via a serial 
link to a second machine or with 
hardware-assisted apparatus can be ef¬ 
fective if you have access to such 
facilities. Lacking these advanced 
capabilities, however, most program¬ 
mers resort to testng the driver code 
by embedding it in a transient test pro¬ 
gram, as they would a TSR. Though con¬ 
structive when properly used, this tech¬ 
nique will not uncover problems that 
may arise only when you operate the 
driver under normal conditions. Recod¬ 
ing your device driver along the lines 
presented in this article can remove 
some of these restrictions and thereby 
help your debugging efforts consider¬ 
ably. 

Listing 2 incorporates code that 
loads a copy of the command.com shell 
on top of the driver's memory image. 
You activate this code at assembly time 
by defining the COMEXEC macro on the 
assembler's command line. With COM- 
EXEC defined, the driver's init routine 
(Listing 3) relocates the break address 
to the end of the JNIT segment, in¬ 
stead of at JNIT:0000 (see Figure 6). 
This causes all transient code inside 
JNIT to remain in memory along with 
the driver itself. With command.com 
loaded, the driver is now pseudo-resi¬ 
dent, and both DOS and your applica¬ 
tions can interact with the driver as 
they normally would under true 
residency. 

Typing "EXIT” on the command line 
unloads the command shell and returns 
control to start_up. start_up then un¬ 
links the driver from the driver chain 
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Listing 5 tdrv.c 

/*. 

* LISTING 5 


char buf[] * 

* 


"Bothered by unsightly bathtub rings?\r\n“ 

* Filename: 

tdrv.c 

Use NEW Duzz-All Cleanser!\r\n\n"; 

* Summary: 

Device driver test bed 


* Author: 

T.W. Nelson 

struct reqhdr ( 

* Compile options: 


char lenj 

* Version: 

1.00 

char unit; 

* Date: 

29-Jan-1992 

char cmdcode; 

* Notes: 


size t status; 

* 


char reserve [8]; 

* MUST compile with byte-packing enabled 

char media; 

* _ 

. */ 

void far *xfer; 

size t count; 

finclude <stdio.h> 


size t sector; 

lindude <stdlib.h> 


) cmdpack * { sizeof(struct reqhdr), 0, 8, 0, 

finclude <dos.h> 


0, (void far *) buf, sizeof(buf), 0 ); 

char Oname[] - “TEMPLATE": //name to search for 

Idefine GROUND ((struct d hdr far *) -1L) 

size t DosDataSeg; 

//DOS data segment 


size t ofsLoL; 

//offset to DOS LoL 

/* .*/ 

size t ofsNULdev; 

//offset to NUL device header 

void err exit( char *errmsg ) { 

size t dosMajor; 

//DOS version #s 

printf( M %s\n\n M , errmsg ); 

size t dosMinor; 


exit(l); 

void (far *strat)(void) 

//-> strategy routine 

} 

void (far *intrp)(void) 
union REGS regs; 

//-> interrupt routine 

void get DOS version(void) ( 

struct SREGS sregs; 


regs.x.ax - 0x3000; 
intdos( Sregs, Sregs ); 

struct d hdr { 


dosMajor * (size t) regs.h.al; 

struct d_hdr far *d_ 
size t d attr; 

next; //-> next header 

dosMinor * (size_t) regs.h.ah; 

size t d strat; 


if( dosMajor < 2 ) 

size_t d_intr; 
char d name [8]; 

): 


err exit ( "Better get a DOS upgrade."); 

) 
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and invokes DOS Terminate Program (int 21h/4ch), which 
returns control to DOS. Once terminated, the driver no longer 
occupies memory. You can thus install the driver any number 
of times for testing; the EXIT command will always wipe the 
slate clean. 


Listing 5 continued 


void get_NUL_device(void) { 

int displacement; 

regs.x.ax - 0x5200; //DOS get list of lists 
intdosx( &regs, &regs, &sregs ); 

DosDataSeg = sregs.es; 
ofsLoL - regs.x.bx; 

switch( dosMajor ) { 

case 2: displacement - 0x17; break; 
case 3: 

if( dosMinor -- 0 ) 

displacement - 0x28; 

else 

displacement = 0x22; 

break; 

case 4: 

case 5: displacement * 0x22; break; 
default: err exit( "Unknown DOS version" ); 

) 

ofsNULdev * ofsLoL + displacement; 

} 

void find_device_header(void) ( 
struct d_hdr far *pdrv; 
size_t d_seg, d_ofs; 
register unsigned i; 

for( pdrv * MK_FP( DosDataSeg, ofsNULdev ); 

pdrv->d_next I* GROUND; pdrv * pdrv->d_next ) ( 

for( i - 0; i < 8; i++ ) ( 

if( pdrv->d_name[i] != Dnamefi] ) 
break; //name doesn't match 

) 

if( i == 8 ) { //found a match 

d seg - FP SEG( pdrv ); 
cTofs • FP~0FF( pdrv ); 
strat = MK_FP(d_seg,d_ofs + pdrv->d_strat); 
intrp ■ MK_FP(d_seg,d_ofs + pdrv->d_intr); 
return; 

) 

) 

printf("Can't find %s device header", Dname); 
err_exit(""); 


main( int argc, char **argv ) { 

regs.x.ax = 0x3d00; //DOS OPEN file, read only 
regs.x.dx = (unsigned) Dname; 
intdos( &regs, &regs ); 

iff regs.x.cflag ) ( 

printf( "%s not installed.", Dname ); 
err exit(““); 

) 

regs.x.bx - regs.x.ax; //handle 
regs.x.ax = 0x4400; //DOS get I0CTL info 
intdos( &regs, &regs ); 

if( 1(regs.x.dx & 0x0080) ) ( 

printf( "%s is a file.' 1 , Dname ); 
err exit(“"); 

) 

regs.x.ax ■ 0x3e00; //DOS close handle 
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Listing 5 continued 


intdos( iregs, iregs ); 
get_DOS_version(); 
get_NUL_device(); 
find_device_header(); 

_ES - FP_SEG( (void far *) &cmdpack ); 

_BX - FP_0FF( (void far *) icmdpack ); 

(*strat)(); //Call the device driver.... 

(*intrp)(); // just like DOS does it 

return 0; 

) 

/*.End of File . */ 


Loading the command shell in this way also means you 
can load a software debugger along with the driver so that it 
too becomes "resident." Invoke the debugger as you normally 
would to debug a program, supplying the driver’s .exe 
filename as the debugger’s argument. Once inside the debug¬ 
ger (at the label start_up), you can set breakpoints at any 
desired location, usually within selected command code 
routines. Next, invoke the debugger's RUN command, which 
will execute the remainder of the start-up code and load the 
command shell without further intervention. You'll then find 
yourself at the DOS command line. 

Once resident, the debugger will pop up whenever a 
breakpoint within the driver is triggered. Simply invoke the 
debugger’s RUN command when you’ve finished stepping 
through the code. There is one important caveat, however: 


you must avoid situations in which breakpoints are activated 
as a result of calls made by the DOS kernel. This problem 
arises, for example, when you use DOS commands such as 
TYPE or COPY to test how your driver responds to a 
device_write call (command code 8). Using /write() to pass 
information to the driver also goes through the DOS kernel. 
Such cases will activate the breakpoints and pop up the 
debugger as always, but your system will eventually lock up, 
the reason being that almost all software-only debuggers make 
DOS calls when activated, since the DOS kernel has activated the 
debugger in this case, any subsequent int 21h calls will reenter 
DOS. Unfortunately, DOS wasn’t designed to allow reentrant calls, 
which corrupt the stack used by the DOS kernel. 

The solution is to use a test bench program that imitates 
the DOS kernel’s interaction with device drivers. Listing 5 
(tdrv.c) presents a working skeleton of such a program. At 
present, tdrv simply passes a nonsense string to the driver 
using command code 8. Function device_write() in the 
driver (Listing 3) responds by writing the string to the screen 
using BIOS video services. If you load the debugger along with 
the driver as described earlier, invoking tdrv will trigger any 
breakpoints you had previously set in the driver code, tdrv 
allows you to pop up the debugger without interference from 
reentrant DOS calls. 

tdrv traverses the driver chain to locate the device header 
for your driver. It then calls the driver’s strategy() and in¬ 
terrupt () routines, which it accesses through the device 
header. The example in tdrv lets you test only command 
code 8 (device_write() in Listing 3). To test a real-world 
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driver, you would have to modify tdrv extensively, adding 
many more test cases —which might lead you to make tdrv 
interactive. Another possibility would be to configure a re¬ 
quest header block by parsing test data you place in a normal 
text file. Such a script-driven version of tdrv could accom¬ 
modate a large number of test cases without recompiling. 

A few warnings are in order when using a driver test bed 
of this nature. A program like tdrv attempts to duplicate the 
DOS kernel's method of making calls to the driver. You must 
therefore know exactly what data DOS places in the request 
block prior to making the call. If you debug based only on 
your assumptions in this regard, you will merely confirm your 
own ignorance. This is particularly true with respect to block- 
type drivers, which involve more complex connections within 
the kernel-to-driver interface. 

To deal with this problem, you might consider equipping 
the driver with some simple instrumentation functions, such 
as data conversion and console output routines. Load your 
driver (with COMEXEC enabled) and invoke a program that will 
output data to the driver via the DOS kernel. At each call to 
exec_command(), call the instrumentation functions to convert 
and display the entire contents of the request block as filled 
in by DOS. As noted earlier, you cannot use a software-only 
debugger in this situation, and you must make sure the in¬ 
strumentation code makes only BIOS or lower-level calls. To save 
the instrumentation output, consider sending it to a printer in¬ 
stead of the console. Spooling to a disk file would require complex 
coding to circumvent DOS’ reentrant limitations. 
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Conclusions 

This article has presented one method of writing a self¬ 
loading DOS device driver. By combining traits of both device 
drivers and TSRs in one program, this method increases your 
flexibility and provides a relative degree of independence from 
the constraints imposed when DOS loads a driver from con- 
fig. sys. The freedom gained also permits the use of debug¬ 
ging techniques comparable to those you might use when 
developing transient programs. 
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Inside Windows NT Security 

Part 2 

Rob Reichel 


Last month (Windows/DOS Developer's Journal, April 1993) I covered some of the 
fundamental concepts of Windows NT security. This month, after a short review, I 
illustrate some of those concepts with a small program that allows an administrator 
to override the normal security on a file. 

A Short Review 

Windows NT offers extensive security features designed to allow it to meet the 
requirements for government C2 security certification. To satisfy these requirements, 
the operating system has to be able to protect resources (such as files) from un¬ 
authorized use. Whenever an operating system object is accessed, Windows NT’s 
security must examine who is making the access request and what security has 
been placed on the object. Most of last month's article described the information the 
security system maintains for users and objects and how it uses that information to 
decide whether to grant or deny any particular access request. 

As I explained in that article, a user could be either a physical user sitting at the 
keyboard or a remote user logged in via the network. The three main pieces of 
security information for users are security ID (SID), group memberships, and 
privileges. The SID uniquely identifies the individual user — it is basically the user's 
machine-readable Windows NT "name.” Each user can reside in one or more groups, 
which provide a convenient means of maintaining security rights as individuals' job 
responsibilities change. Finally, to handle special cases that require overriding normal 
security, each user can have privileges. For example, a backup privilege could enable 
someone to back up all files on a system without having to have read access to all 
those files. All this security information about a user resides in something called an 
access token. 

Each securable Windows NT object also has a collection of security information, 
called a security descriptor. One part of the security descriptor is the SID of the 
object's owner. An object's owner can perform almost any action on that object. 
Another part of a security descriptor is the System Access Control List (SACL). This 
specifies what kind of object access should generate audit messages that can later 
be reviewed by the system administrator. Finally, the most complex part of an 
object’s security descriptor is the Discretionary Access Control List (DACL). This is a 
detailed list of security information; each entry in the list grants or denies specific 
kinds of access to a specific user or group of users. 

Windows NT security works in a uniform way for a variety of operating system 
resources, not just files. Internally, all of these resources (such as files, pipes, 
semaphores, and so on) are objects, and each request to access one of these objects 
goes through the Windows NT security manager. The security manager uses certain 
algorithms (described in last month’s article) to decide whether to grant or deny 
access to the object. 


Rob Reichel graduated from Princeton University in 1985 with a BSE/EECS, and has 
been working on operating systems for Microsoft ever since. He is currently working 
on the Windows NT security system. Rob lives in Redmond, Washington, with his wife 
Jackie and the cats, Moxie and Fang. You can contact him on CompuServe at 
72360,3504 (72360.3504@compuserve.com from the Internet). 
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A Security Example 

1 will describe how to write a small program (take.exe) that lets an administrator 
override the normal security on a file. I say “an administrator” because the Ad- 
minstrator account has special privileges (or "rights”) not normally found in regular 
user accounts. These privileges allow the administrator to perform security-related 
actions that no other user of the machine should be allowed to do. The source to 
take.exe is in Listing 1, and you may want to refer to it as you read the description 
that follows. 

Even though this program duplicates features found in the File Manager, under¬ 
standing it and the problem it solves is important to understanding the basics of NT 
security. Anyone wishing to write applications that manipulate the security at¬ 
tributes of files or other objects in NT should be comfortable with the concepts I 
discuss here. 

An important note: NT currently supports three file systems — FAT, FIPFS, and 
NTFS. Of the three, only NTFS allows placing security information on files. While 
take.exe will appear to work on FAT and HPFS, it quietly does nothing. It is much 
more interesting to run it on NTFS, where you can readily observe its actions. 

The Problem 

In order to make this an interesting exercise, log on to Windows NT as a normal 
user (not an administrator). Create a dummy file on an NTFS partition and select it in 
the File Manager. From the File Manager’s Security menu, select "Permissions." 
Remove any permissions and add an entry giving "Everyone” “No Access.” This tells 
the File Manager to put an empty Discretionary Access Control List (DACL) on the file. 
Since you are the creator of the file, your security ID (SID) is now the owner of the 
file. 

Since you are the owner of the file, you could just start the File Manager again 
and put another DACL on the file that does whatever you'd like. But suppose you 
are the system administrator, you discover this file, and its owner is no longer avail¬ 
able. You can’t just change its DACL, because its current DACL denies everyone (in¬ 
cluding an administrator) access. You would have to run a program that does some¬ 
thing similar to what take.exe does. 

To demonstrate the problem you’re up against, log on to the Administrator ac¬ 
count and try to do something to the file. Try anything. Try to delete the file or even 
just type it out. You'll be told “Access Denied.” There’s no way for you to get rid of 
the file (and reformatting the disk is cheating!), take.exe tackles the problem by 
taking steps to: 

• Initialize data structures 

• Attempt to replace the DACL on the file by the most straightforward approach 

• If necessary, enable SeTakeownership privilege and replace the owner on the file 

• Once again attempt to replace the DACL on the file. 

Figure 1 provides a schematic of roughly what happens up to the first attempt to set 
the file security. 
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Figure 1 Preparing to call SetFileSecurityO 



empty DACL 


DACL with single 
access control entry 


Listing 1 newtest.c 


linclude <windows.h> 
linclude <malloc.h> 
linclude <stdio.h> 
linclude <process.h> 

BOOL EnableTakeOwnershipPrivilege( 
HANDLE TokenHandle, 

PTOKEN PRIVILEGES OldPrivileges 
); 

BOOL OpenToken( 

PHANDLE TokenHandle 
); 


VOID _CRTAPI1 main (int argc, char *argv[]) 

{ 

int i; 

PACL Dacl; 

LPSTR FileName; 

TOKEN_PRIVILEGES OldPrivileges; 

SID_IDENTIFIER_AUTHORITY NtAuthority - SECURITY_NT_AUTHORITY; 
PSID AdminAliasSid; 

BOOL Result; 

ULONG DaclSize; 

HANDLE TokenHandle; 

SECURITY_DESCRIPTOR SecurityDescriptor; 

if ( argc <- 1 ) { 

printf("No file specified\n"); 
exit(-l); 

} 


Result « AllocateAndInitializeSid( 
ANtAuthority, 2, 

SECURITY BUILTIN_DOMAIN RID, 
DOMAIN ALIAS_RID_ADMINS7 
o, o, o, o, o, o7 

AAdminAliasSid 
); 


if ( 1 Result ) { 

printf("Unable to allocate memory for SIDs\n"); 
exit(-l); 

} 


Result ■ OpenToken( &TokenHandle ); 
if ( (Result ) { 

printf("Unable to open token\n"); 
exit(-l); 


// Build the new Security Descriptor to put on 


Constructing the Data 
Structures 

The first thing take.exe has to do is 
initialize its data structures. Since 
take.exe is going to loop through all 
the files specified on its command line, 
performing its initialization up-front 
means that it will have ready all the 
data it needs to interact with the 
Win32 security functions. 

Building the SID 

take.exe will attempt to create a 
DACL that allows administrators full ac¬ 
cess to the file and then will place that 
DACL on the file. It may first have to 
make "Administrators" the owner of the 
file. It can use the same SID both for 
the new owner and in the new DACL, 
so it builds the SID once here with a 
call to AllocateAndInitializeSid(). 
This routine figures out how much 
memory will be required by the SID, al¬ 
locates the memory, and fills in the 
passed values. The call in take.exe is: 

Result = AllocateAndInitializeSid( 
&NtAuthority, 2, 

SECURITYBUILTIN_D0MAIN_RID, 
DOMAIN_ALIAS_RID_ADMINS, 

0 , 0 , 0 , 0 , 0 , 0 , 

&AdminAliasSid); 

which results in the following SID: 


S-l-5-32-544 

Building the DACL 

Once the SID has been assembled, 
the new DACL for the file can be con¬ 
structed. take.exe calculates exactly 
how much space will be required by 
the new DACL and allocates just that 
much. Calculating how much space is 
needed requires knowing what the 
various data structures that are going 
to go into the DACL look like. Unfor¬ 
tunately, DACLs are so arbitrarily com¬ 
plex that it isn't possible to have an 
AllocateAndlnitializeACL() routine, 
though such a thing would be quite 
helpful. This calculation requires the size 
of the SID in order to know how much 
space to allocate for the DACL, which is 
why I constructed the SID first. 

The buffer allocated for the DACL 
must be initialized with a call to 
InitializeAcl(). This builds the 
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header information at the beginning of 
the buffer and generally prepares the 
way for placing access control entries 
(ACEs) into the DACL. 

I will put one ACE into the ACL which 
will grant GENERIC_ALL access to 
anyone who is in the Administrators 
group. Since assembling the pieces of 
an ACE and getting it right is tedious 
and error-prone, Windows NT provides 
an easy-to-use Win32 function that 
takes all the necessary information and 
correctly puts it into the DACL. In 
take, exe this call is as follows: 

Result = AddAccessAllowedAce( 

Dacl, ACL_REVISI0N2, 
GENERIC_ALL, AdminAliasSid); 

The corresponding call to put an AC- 
CESS_DENIED ACE into the ACL would be 
AddAccessDen i edAce(). 

Building the Security 
Descriptor 

Once I've finished building the DACL, 
I can put it into the security descriptor. I 


Listing 1 continued 


// the file. 

// This will only fail if the revision is wrong, but 
// it's good to be prepared for anything. 

Result ■ InitializeSecurityOescriptor( iSecurityDescriptor, 
SECURITY_OESCRIPTOR_REVISION ); 

if ( !Result ) { 

printf("Unable to initialize Security Descriptor\n"); 
exit(-l); 

} 

// Compute the size of the buffer needed for the 
// DACL. 

DaclSize ■ sizeof( ACL ) + 

sizeoff ACCESS ALLOWED ACE ) - 
sizeof( ULONG ) ~ ♦ 

GetLengthSid( AdminAliasSid ); 

Dacl - malloc( DaclSize ); 

if ( Dacl « NULL ) { 

printf("Out of memory\n"); 
exit(-l); 

} 

Result - InitializeAcl ( Dacl, DaclSize, ACL_REVISI0N2 ); 
if ( (Result ) { 

printf("Unable to initialize ACL, error ■ %d\n",GetLastError()); 
exit(-l); 

} 

Result ■ AddAccessAllowedAce ( 

Dacl, 

ACL_REVISI0N2, 

GENERIC_ALL, 

AdminAliasSid 
): 
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Listing 1 continued 


if ( I Result ) { 

printf(“Unable to add ACE, error - %d\n",GetLastError()); 
exit(-l); 


Result ■ SetSecurityDescriptorDacl ( 

ASecurityDescriptor, 

TRUE, 

Dacl, 

FALSE 

); 

if ( I Result ) { 

printf("Unable to add ACL to security descriptor, error ■ 
%d\n",GetLastError()); 
exit(-l); 


Result - SetSecurityDescriptorOwner( 

ASecurityDescri ptor, 

AdminAliasSid, FALSE 

); 

if ( I Result ) { 

printf(“Unable to set owner, error ■ %d\n",GetLastError()); 
exit(-l); 


for (i-1; i<argc; i++) { 

FileName * argv[1]; 

printf("\nFile: %s\n",FIleName); 

Result ■ SetFileSecurity( 

FileName, 

DACLJECURI TY_I N FORMAT I ON, 

ASecurityDescriptor 

); 

if ( Result ) { 

printf("\s: Dacl replaced\n",FileName); 
continue; 

} 

// If the attempt to change the DACL didn't work, 

// we have to make Admin the owner. Just try it 
// first, and then try it with a privilege. 

Result - SetFileSecurity( 

FileName, 

OWNER_SECURITY_INFORMATION, 

ASecurityDescriptor 

); 

if ( (Result ) { 

// The attempt to make Admin the owner of 
// the file failed. Use SeTakeOwnership 
// privilege. 

Result - EnableTakeOwnershipPrivilege( 

TokenHandle, 

AOldPrivileges 

); 

if ( (Result ) ( 

// This account doesn't have SeTakeOwnership 
// privilege. Tell them to try running it again 
// from an account that does. 

printf ("Unable to enable SeTakeOwnership privileged"); 
printf("Try running take again from the Administrator account\n"); 
printf("%s: skipped\n",FileName); 
continue; 

} 

Result - SetFileSecurity( 

FileName, 

OWNER_SECURITY_INFORMATION, 

ASecurityDescriptor 

); 

If ( (Result ) { 

// This shouldn't fail, but it can. 

printf ("Unable to set file owner with privileged"); 

printf ("Terminatingd"); 

exit(-l); 

} 

// Turn off SeTakeOwnership privilege. 

(VOID) AdjustTokenPrivileges ( 

TokenHandle, 

FALSE, 

AOldPrivi leges, 

sizeof( T0KEN_PRIVILEGES ), 

NULL, 

NULL 

); 

if ( GetLastError() 1- N0_ERR0R ) { 

// This is unlikely to happen, 

printf ("AdjustTokenPrivi leges failed turning off SeTakeOwnership privileged"); 


do this with the call to SetSecurity¬ 
DescriptorDacl (). I also indicate that 
the Dacl Present flag should be set in 
the security descriptor, and that the 
DACL was not derived from a defaulting 
mechanism. In addition to setting the 
DACL in the security descriptor, I also put 
the AliasAdminSid into the owner field. 

The reason for doing it this way is 
that l can load up a security descriptor 
with all four possible pieces of informa¬ 
tion (the owner, group, DACL, and SACL), 
but tell the system to only pay atten¬ 
tion to certain pieces at a time. Since at 
one point in the program I want to set 
the DACL on the file, and at another 
point I'm going to want to set the 
owner, I might as well load up both 
pieces now and just use what I need 
when I need it. This will become clearer 
when I get to the SetFileSecurityO 
calls. 

Applying the Security 
Descriptor to a File 

Since all I really want to do is 
change the DACL on the file, that is 
what I’ll try first. If it doesn’t work, I’ll 
take stronger measures that I know will 
work. 

Why not start with the stronger 
measures? First, the program makes a 
better learning tool by illustrating how 
to use increasingly sophisticated 
measures to achieve its goal. But more 
important, it’s bad design methodology 
to employ security overrides you don’t 
really need. Frequently, it isn’t the right 
thing to do at all. For example, suppose 
you wanted to write a program like the 
File Manager that allows users to copy 
and delete files. To immediately employ 
every possible security override in order 
to accomplish a file copy or delete 
operation would be a bad design 
decision, because the user may have 
made a mistake in requesting that 
operation. 

Security-aware programs like the File 
Manager should make the user issue a 
specific order before attempting to 
override the normal security on a file. 
Such programs may then turn around 
and use every trick in the book to ac¬ 
complish the operation, but not before. 

take.exe calls SetFileSecurityO 
to change the DACL on the file. Set¬ 
FileSecurityO performs several 
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operations on behalf of the user. First, it 
examines which part of the file's 
security descriptor is being changed, 
and attempts to open up the file for the 
access required to make the change. If 
that succeeds, it replaces the specified 


piece of the security descriptor, closes 
the handle it got during the open call, 
and returns. Since the security of files 
receives more attention than the 
security of most other objects, Microsoft 
provided SetFileSecurityf) to make 
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Listing 1 continued 


) 

Result * SetFileSecurity( 

FileName, 

DACL_SECURITY_INFORMATION, 

ASecurityDescriptor 
); 

if ( Result ) { 

printf("%s: Dacl replaced\n",FileName); 
continue; 

} else { 

// This shouldn't fail, but it can. 

printf("Unable to set DACL of file owned by Admin\n"); 

printf("Terminating\n"); 

exit(-l); 

} 

} 

} 

} 

BOOL EnableTakeOwnershipPrivilege( HANDLE TokenHandle, 

PTOKEN_PRIVILEGES OldPrivileges ) 

{ 

TOKENPRIVILEGES NewPrivileges; 

BOOL Result; 

LUID TakeOwnershipValue; 

ULONG ReturnLength; 

Result * LookupPrivilegeValue( 

NULL, "SeTakeOwnershipPrivi1ege", 

ATakeOwnershipVal ue 
): 

if ( 1 Result ) { 

printf("Unable to obtain value of TakeOwnership privilege\n"); 
return FALSE; 

} 

// Set up the privilege set we will need 
NewPrivileges.PrivilegeCount ■ 1; 

NewPrivileges.Privileges[0].Luid = TakeOwnershipValue; 

NewPrivi1eges.Privi1eges[0].Attributes = SE_PRIVILEGE_ENABLED; 

(VOID) AdjustTokenPrivileges ( 

TokenHandle, FALSE, 

ANewPrivileges, 

sizeof( T0KEN_PRIVILEGES ), 

OldPrivileges, AReturnLength 
); 

if ( GetLastError() != N0_ERR0R ) 
return( FALSE ); 

else 

return( TRUE ); 

} 

BOOL OpenToken( PHANDLE TokenHandle ) 

{ 

HANDLE Process; 

BOOL Result; 

Process » OpenProcess( 

PROCESS_QUERY_INFORMATION, 

FALSE, GetCurrentProcessId() 

); 

if ( Process ■■ NULL ) { 

// This can happen, but is unlikely, 
return( FALSE ); 

} 

Result * OpenProcessToken ( 

Process, 

TOKEN_ADJUST_PRIVILEGES | TOKEN_QUERY, 

TokenHandle 

): 

CloseHandle( Process ); 
if ( !Result ) ( 

// This can happen, but is unlikely, 
return( FALSE ); 

} 

return( TRUE ); 


/* End of File */ 
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common operations easier for applications to perform. 

In fact, SetFileSecurityO may sometimes be the only 
way to change the security on a file. Alternatively, you could 
call CreateFile() for the access needed to change the 
security descriptor, followed by SetKernelObjectSecurity() 
to perform the changes. There is one subtle problem with this 
approach, however: CreateFile() will always attempt to 
open the file for SYNCHRONIZE access in addition to whatever 
other access you pass in. This can interfere with attempts to 
change the security descriptor of the file. SetFileSecurityO 
always tries to open the file for the least amount of access 
needed to change the security descriptor. 

The second parameter to SetFileSecurityO tells the sys¬ 
tem which part of the passed security descriptor to pay atten¬ 
tion to. Even though an owner is set in the passed security 
descriptor, passing DACL_SECURITY_INFORMATION causes it to 
be ignored. 

Using Privileges to Override the DACL 

If SetFileSecurityO does the job, take.exe will move on 
to the next file specified. If you set up the file to allow no 
access, as I suggested earlier, then this call to SetFile¬ 
SecurityO won't be able to do anything. The next step is to 
try to change the owner on the file, which, like the attempt to 
change the DACL, may or may not fail. 

Since I set the owner field of the security descriptor earlier 
on, I can use this same security descriptor to try to change 
the owner by specifying OWNER_SECURITY_INFORMATION in the 
call to SetFileSecurityO. If this attempt to change the 
owner fails, it will be necessary to use a privilege to get the 
job done. The subroutine EnableTakeOwnershipPrivilege() 
sets things up so that this is possible. 

The first thing EnableTakeOwnershipPrivilege() must do 
is look up the value of the privilege (it is a good idea not to 
hard-code privilege values into applications, but rather to 
query their values at startup or when needed). Once the value 
of the privilege is known, I put it into a T0KEN_PRIVILEGES 
structure and pass it into the system. This is a variable-length 
structure composed of a header and any number of privilege 
values. If you need to adjust more than one privilege, you will 
have to compute the size of the structure with a calculation 
similar to the one I used to compute the required size of the 
ACL. 

The call to AdjustTokenPrivileges() is the heart of the 
subroutine. There is one important thing to notice about the 
call to AdjustTokenPrivileges(): you don’t need to examine 
its return value. This is because, unlike most other API calls, 
AdjustTokenPrivileges() has three possible results: com¬ 
plete failure, complete success, and somewhere in between. 
The “somewhere in between" case occurs when you pass in 
multiple privileges, and some are found in the token and 
some are not. In this case, those that are found are enabled 
and the rest are ignored, but the API function will set Last- 
Error to tell you what happened. So the rule of thumb is, 
always call GetLastError() for the true story of what hap¬ 
pened during a call to AdjustTokenPrivileges() ( Adjust- 
TokenGroupsf) has similar semantics). 

Windows NT places privileges in an access token when the 
token is created, based on the groups and rights assigned to 


the subject. Not all tokens will contain all privileges, and in 
fact, most tokens will contain very few of the available 
privileges. There is no way to change the privileges in an ex¬ 
isting token. Rather, the system administrator would have to 
modify the account information for the user and specify that 
the desired privileges be placed in the user’s token the next 
time the user logs in. 

Changing the Owner 

Now that SeTakeOwnership privilege has been enabled, I 
can be sure that I’ll be able to change the owner of the file, 
and once that is done, I will be able to modify the DACL of the 
file. Note that immediately after setting the owner of the file, I 
turn off SeTakeOwnership privilege in my token. In general, it 
is good practice to have privileges enabled only for the dura¬ 
tion of the time you know that you’re going to need them. 
Otherwise, they may have unintended and undesirable side 
effects (such as deleting at some later point a file that should 
not be deleted). 

Rather than simply turning off the privilege, I call Adjust¬ 
TokenPrivileges () again with the previous state of the 
privilege 1 changed. This allows me to restore the privilege to 
the state it was in before I started modifying it, rather than 
just turn it off and potentially cause problems to the calling 
code (assuming this is taking place in the framework of a 
larger application). 

Conclusion 

I didn’t write this program to be as efficient as possible, 
but rather to illustrate design principles for security-aware ap¬ 
plications. Were this to be a true "quick and dirty" tool, it 
would enable the privilege once up-front, blast the owner and 
DACL information onto each file, and be done with it. How¬ 
ever, in complex applications that are not as straightforward 
as this one, it pays to wield the power of the security system 
carefully and only when necessary. In fact, most applications 
will never need to manipulate security information at all, but 
those that do must be very careful not to cause dangerous 
side effects that could destroy large amounts of information. 

Understanding how this program works also helps you to 
understand why it is bad practice to use accounts with lots of 
privileges except when really necessary, take.exe can only 
use SeTakeOwnership privilege in an account that has that 
privilege, which is normally only an Administrator account. 
While it may be tempting for a system administrator to set up 
all of the users of the system as administrators or near ad¬ 
ministrators, such users are open to attacks by "Trojan Horse” 
programs that use the same techniques as take.exe to either 
steal or destroy data. It is for this reason that privileges should 
be granted sparingly, or not at all, and those who have 
privileges should be very careful only to run software that 
they trust absolutely. 
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Automatic 3-D Text 
and Graphics Pushbuttons 

David Spector 


Windows™ endowed its built-in dialog box pushbuttons with a nice 3-D look — 
they appear to press in when you click on them with the left mouse button or 
with the space bar — but limited their display capability to a single line of 
centered text. 

Some vendors, such as Borland, supply custom control libraries (e.g., bwcc.dll) 
capable of displaying bitmaps on pushbuttons and other controls. These tools, 
however, require you to supply at least two bitmaps — one for the normal state 
and one for the depressed button state. If you want 3-D effects, you’ll have to 
build them manually into each bitmap. 

It would be handy if you could somehow specify that a button's caption was 
to appear raised (embossed) or engraved on the button’s surface. It would also be 
nice if you could create one bitmap file and display it on the surface of 3-D 
pushbuttons with a minimum of programming effort. Handiest of all would be the 
ability to create two bitmaps — one containing the graphics and one in “false 
color” as a key to describe which areas move, which areas are raised, and which 
areas are engraved on the button — and have the computer do the rest. This 
article describes a function package that does all this and a lot more. 


David Spector has been programming small computers for 27 years. During the last 14 
years he has been a compiler writer. In the last year David has been offering Windows 
development tools through his own company. Springtime Software. You may contact 
him there at (617) 894-94 55. 
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The Basic Elements of 3-D 

The basic visual elements of 3-D images are color and loca¬ 
tion. By brightening a color you can simulate the effect of a 
light source shining on its surface. By darkening a color you 
can simulate the effect of a surface in shadow. You can add a 
background shadow if there is some (simulated) distance bet- 
weeen the image and the background. Finally, you can move 
a portion of the image in two dimensions to help simulate its 
motion in three dimensions. 

There is another intriguing effect that you can use: certain 
bright colors seem (by an optical illusion) to be floating on top 
of or underneath the display surface. For example, for me, 
bright red seems to float above gray. However, since this ef¬ 


fect restricts your use of color and presumably also varies 
from person to person, I don't allow it to be used automat¬ 
ically in my function package. 

Using these 3-D effects, you need only construct two inter¬ 
nal bitmaps associated with each pushbutton: one for the up 
state and one for the down state. Painting them will then be 
very fast, and fast painting will help sustain the illusion you 
are creating. 

You can associate the bitmaps with the button by using 
window properties. Window properties are 16-bit integers (in 
this case, bitmap handles) you can store and retrieve using an 
arbitrary character string as the property's name (see the Win¬ 
dows documentation for GetPropO and SetPropO). 

A detailed look at simple Windows pushbuttons reveals 
the following: 

• The overall 3-D effect derives from 
rectangles surrounding the surface of 
the control. The standard control 
surface for all standard color 
schemes is light gray with black text, 
although this can be changed by 
using the Color applet in the Control 
Panel. 

• The outermost button frame is a 
one-pixel-thick black rectangle (if the 
button is a default pushbutton, the 
frame is two pixels thick, with the 
extra frame taken from space inside 
the control). I discuss making the 
button frame itself 3-D later (this 
looks a lot nicer than plain black). 

• Inside the button frame, the button 
sides are represented by a rectan¬ 
gular layer two pixels wide. At the 
left and top, these pixels are white. 
At the right and bottom, these pixels 
are gray. The difference in color 
simulates the illumination and shad¬ 
ing that would be caused by the 
standard Windows bright light 
source located on a 45-degree 
diagonal at the top left. 

• The four pixels comprising the right 
top and left bottom edges of the 
button sides are ambiguous, because 
they lie on a slope. You can convinc¬ 
ingly color them white, gray, or light 
gray, just so long as you are consis¬ 
tent. My best results have come 
from coloring them the same as the 
adjacent horizontal line for left/bot¬ 
tom pixels and the same as the ad¬ 
jacent vertical line for right/top 
pixels. 

• When a button is pressed in (so that 
it is in the down state), the button 
surface moves two pixels to the 
right and two pixels down. The but¬ 
ton sides disappear (turn to light 
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gray) except for two gray lines (at the left and top) that 

simulate the shadow cast by the button window onto the 

button sides. 

The lines referred to here (and throughout the article) are 
specific to the VGA screen resolution of 640x480 pixels, where 
the SM_CXB0RDER and SM_CYB0RDER display metrics are both 
equal to one pixel. You can generalize the thickness of these 
lines by using GetSystemMetrics () to obtain the actual sys¬ 
tem border thickness. A Windows user with access to greater 
display resolution could then choose between displaying more 
material on the screen (by keeping the border thickness equal 
to one) or displaying roughly the same amount of material, 
but at a higher definition (by increasing the border thickness 
and other system display metrics). 

Subclassing or Ownerdraw 
Buttons? 

As Paul Bonneau pointed out in his 
Q&A column (Windows/DOS Developer’s 
Journal, Sept. 1992: p. 59), bitmap- or 
icon-painted pushbuttons can be imple¬ 
mented either by subclassing standard 
pushbuttons or by using ownerdraw 
pushbuttons. 

There are actually two types of 
pushbuttons that are designed to be 
drawn by the parent window (that is, 
by the dialog box) and thus can be con¬ 
sidered ownerdrawn: ownerdraw but¬ 
ton controls and user buttons. Windows 
handles mouse left-button clicks and 
keyboard input for both of these stand¬ 
ard button styles. 

User buttons are the older and 
simpler of the two. They have the 
BSJJSERBUTTON control style and send 
UM_C0MMAND messages to their parent 
window. These messages include a 
notification code indicating the button's 
state (though only the BN_CLICKED 
notification code is really useful). Al¬ 
though user-drawn buttons handle the 
drawing of the focus rectangle themsel¬ 
ves (unlike ownerdraw buttons proper) 
and are easier to program (because of 
the UM_C0MMAND messages) for 2-D areas 
that must act like pushbuttons, 

Microsoft® recommends against their 
use in new software because of their 
limitations. 

Ownerdraw buttons proper have the 
button style BS_0WNERDRAW. Whenever 
their display must change to match 
their state (that is: newly-drawn, having 
the focus, or being pushed down), Win¬ 
dows sends a HM_DRAUITEM message to 
the parent window. This message in¬ 
cludes a pointer to a DRAUITEMSTRUCT 


structure that contains detailed state and style information, so 
that very generalized control painting functions can be writ¬ 
ten. Ownerdraw control types include not only pushbuttons 
but also comboboxes, listboxes, and menus. 

Strangely, neither ownerdraw controls nor user buttons 
send a message to their parent when they are destroyed, 
which means that the freeing of associated GDI or global 
memory objects will not occur routinely. However, dialog pro¬ 
cedures do get a WM_DESTROY message when they are 
destroyed, so they can just scan all their buttons at that time, 
using EnumChildWindows(). 

Paul Bonneau presents sample code in the column showing 
how to subclass each pushbutton to be painted with an 
image. He points out that the advantage of subclassing for 
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such pushbuttons is that it reduces the 
programming effort, since pushbuttons 
already draw their own frames and 
sides, and so on. In addition, subclassing 
lets you avoid having to change dialog 
procedures to handle 3-D pushbuttons 
(because all the processing is done in 
the new subclassing window proce¬ 
dure). Subclassing also handles more 
generalized functionality (such as 
releasing extra GDI and/or global 
memory objects automatically when a 
3-D pushbutton or its dialog box is 
destroyed). In practice, however, sub¬ 
classing a pushbutton sometimes has a 
slight drawback — an annoying flicker 
when a button is pushed or released. 
The flicker results from the painting 
done by the original button window 


procedure, particularly if the button has 
a caption (I can actually read the cap¬ 
tion by pressing such a button several 
times in quick succession on my sys¬ 
tem). 

Demonstration Programs 

I have implemented demonstration 
programs using both the subclassing 
and ownerdraw button methods, but I 
focus on the ownerdraw approach here 
because it avoids the flicker problem. 

I have written a program called 
btn.exe to demonstrate the button 
routines described in the remainder of 
the article. The complete source code 
for this program and all the bitmaps it 
uses is available on the code disk. 


Graying A Button Surface 

when a pushbutton is disabled, any graphics or text on its surface must be 
grayed. There is no single Windows API function that accomplishes this graying, 
but it is not really very difficult to do. 

The first step is to AND the pixels with a light gray brush, using PatBlt(). 
This mutes any very bright colors: no color will be brighter than light gray 
because of the AND'mg operation. 

void gray_area(HDC dc, LPRECT Ipr) 

{ 

HBRUSH brush; 

HBITMAP gray_bitmap; 

/* AND with solid Light Gray brush: Makes colors darker */ 

SelectObject(dc, GetStockObject(LTGRAY_BRUSH)); 

PatBlt(dc, lpr->left, lpr->top, WIDTH(1pr), HEIGHT(Ipr), 
PATANDDEST /* P & D */); 

Darker colors, however, will survive intact, so a second step is needed —to 
OR the pixels with a brush constructed from a special 8x8 pixel bitmap checker¬ 
board of black and light-gray pixels. 0/?ing with this brush sprinkles the darker 
colors with a pattern of light gray dots, producing the final more-or-less satisfy¬ 
ing visual effect of a disabled control. 

/* OR with Light Gray/Black checkerboard to make the 
picture appear lighter again with gray dots */ 
gray_bitmap = LoadBitmap(instance, "gray_brush"); 
if (!gray_bitmap) 

fatal("gray brush bitmap could not be loaded", NULL); 
brush = CreatePatternBrush(gray_bitmap); 

SelectObject(dc, brush); 

PatBlt(dc, lpr->left, lpr->top, WIDTH(lpr), HEIGHT(lpr), 

PATORDEST /* P | D */); 

SelectObject(dc, GetStockObject(WHITE_BRUSH)); 

del(brush); 

del(gray_bitmap); 
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3-D Effects on Buttons 

Standard Windows pushbuttons dis¬ 
play text as black on light gray, but 
there is nothing to prevent you from 
achieving a 3-D effect in the button 
text. You can have your text either 
engraved on (etched into) the control 
surface, or raised up from it (embossed 
on it). 

To engrave text, display it twice. 
First, display it in white slightly to the 
right and down from its original posi¬ 
tion. This simulates the brightly lit sides 
of the engraving. Next, display it in 
black (actually, you should use the sys¬ 
tem color BTNTEXT) in its original posi¬ 
tion. This simulates the bottom of the 
engraving. 


To raise text, display it three times. 
First, display it in white slightly to the 
left and up from its original position. 
This simulates the brightly lit sides of 
the raised text. Next, display it in gray 
slightly to the right and down from its 
original position. This simulates the 
shadowed sides of the raised text. Final¬ 
ly, display the text in black in its 
original position, to simulate the top of 
the raised text. 

Another effect to consider is the dif¬ 
ference between the image on the bit¬ 
maps for the two button states (up and 
down). To make the text move with the 
button, shift it to the right by two 
pixels and down by two pixels (because 
the button surface itself moves that 
way). To make the text float above the 


The gray_area code 

#define WIDTH(lprect)\ 

(Oprect)->right - (lprect)->left) 

#define HEIGHT(lprect)\ 

((lprect)->bottom - (lprect)->top) 

makes use of the convenient WIDTH and HEIGHT macros, which calculate the 
width and height of a given rectangle. 

The gray_brush bitmap resource needs only two colors, so it can use the 
1-bit-per-pixel mode for better efficiency than the 4-, 8-, or 24-bit-per-pixel color 
modes that Windows supports for bitmaps. As you see in the definition below, 
most of the bitmap consists of the 3-byte unused (and zero) pieces needed to 
fill out each of the eight 32-bit scan lines; the Device-Independent Bitmap (DIB) 
format does not lend itself to efficient use of memory unless the number of bits 
used in representing the width of the bitmap happens to be a multiple of 32. 

/* Borland's Resource Compiler handles hex bitmaps, 
but Microsoft's unfortunately does not */ 

Gray_Brush BITMAP 
BEGIN 

'42 40 5E 00 00 00 00 00 00 00 3E 00 00 00 28 00' 

'00 00 08 00 00 00 08 00 00 00 01 00 01 00 00 00' 

'00 00 20 00 00 00 00 00 00 00 00 00 00 00 00 00 ' 

'00 00 00 00 00 00 00 00 00 00 BF BF BF 00 55 00' 

'00 00 AA 00 00 00 55 00 00 00 AA 00 00 00 55 00' 

'00 00 AA 00 00 00 55 00 00 00 AA 00 00 00' 

END 

In this case the width of the bitmap is 8 and the bits per pixel is 1, so the width 
is represented by 8 bits. This is not a multiple of 32, so an extra 24 bits have to 
be added for each horizontal scan line in the bitmap. Since there are 8 scan 
lines (because the height of the bitmap is 8), 24 * 8 = 192 bits are wasted. □ 
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Figure 1 Eight possible 3-D effects for button surfaces 


Dialog Surface 


Button is Up 

2 



6 


x_r 


Dialog Surface 


Button is Down 


5 




0. A 3-D background that "moves" as the button is pressed. 

1. Areas that are flat, but move as the button is pressed. 

2. Areas that are raised, and move as the button is pressed. 

3. Areas that are engraved, and move at the button is pressed. 

4. A 2-D background that "floats" as the button is pressed. 

5. Areas that are flat, and float as the button is pressed. 

6. Areas that are raised, and float as the button is pressed. 

7. Areas that are engraved, and float as the button is pressed. 


Listing 


btn fncs.h 


/* Fatal error procedure type */ 
typedef void ERRPR0C(LPSTR msg, long info); 


/* Initialize 3-D button facility (call from start of application) */ 
void init_3d(LPSTR app_name, HANDLE instance, ERRPROC fatal); 

/* Terminate 3-D button facility (call from end of application) */ 
void end_3d(void); 

/* Initialize or terminate all 3-D buttons in a dialog box */ 

/* (call from WMJNITDIALOG and WM_DESTROY) */ 
void scan_3d_buttons(HWND dig, LPARAM pass); 


/* Paint a 3-D button in a given new state (call from WM_DRAWITEM) */ 
void paint_3d_button(DWORD IParam); 

/* For debugging: Display given DC+bitmap in center of screen */ 
void show(HDC dc_in); 


/* End of File */ 


button when the button is depressed, 
copy the text identically onto the up 
and down bitmaps. 

Another possible technique is to en¬ 
hance the floating text effect by draw¬ 
ing a shadow of the text when the but¬ 
ton is depressed. To accomplish this, 
copy the text in gray onto the back¬ 
ground, shifting it three pixels to the 
right and three pixels down. The extra 
pixel shift makes the shadow move 
faster than the 2-D image, and this 
makes the shadow appear more realis¬ 
tic. 

I use methods similar to these for 3- 
D graphics and frames, while displacing 
and changing the color of a line or area 
is not a perfect simulation (particularly 
if the border-thickness metric is greater 
than one), it is quite convincing in prac¬ 
tice and is easy to program. 

3-D Pushbutton Frames 

The frame around a control is usual¬ 
ly just a one-pixel thick black rectangle 
(two, if the control is a default pushbut¬ 
ton). You can create a more striking 
visual effect by drawing the frame in 3- 
D, along with the control itself. Since a 
button protrudes from (or towards) the 
dialog box surface, a 3-D frame similarly 
drawn as a ridge raised from the sur¬ 
face looks better than a frame drawn 
as a furrow etched into it. 

A nice-looking 3-D control frame, 
then, is a “ridged” rectangle three pixels 
thick. In each three-pixel-thick frame, 
the left or top line is white, the right or 
bottom line is gray, and the middle line 
is light gray, to simulate the standard 
lighting effects on a ridged rectangle. 
The right-top and left-bottom pixels of 
illuminated frame lines are ambiguous; 
you can create a reasonable effect by 


Figure 2 Addition to Dialog 
Box Procedures 


switch (message) 

{ 

case WMJNITDIALOG: 

scan_3d_buttons(dlg, 0); 
return TRUE; 
case WM_DRAWITEM: 

paint_3d_button(1 Pa ram); 
return TRUE; 
case WM_DESTR0Y: 

scan_3d_buttons(dlg, 1); 
break; 

case WM COMMAND: 
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Listing 2 btnjncs.c 


linclude <windows.h> 


Idefine min(a, b) ((a) < (b) ? (a) : (b)) 

linclude "btn_fncs.h" 


lendif 

Idefine WIDTH(lprect) ((lprect)->right - (lprect)->left) 

/♦ Standard declarations */ 


Idefine HEIGHT(lprect) ((lprect)->bottom - (lprect)->top) 

Idefine EQ — 


Idefine IDLEN 128 

#define NE I- 


typedef enum {SAME COLOR, DARKER, BRIGHTER, SHADOW} BRIGHTNESS TYPE; 

Idefine NUL *\0' 


typedef enum {NO MOVE*-MOVEMENT, MOVE-O, END-100} MOVE TYPE; 

Idefine STRCMP lstrcmp 


HDC dc_up, dc_down, dc_button, dcjjitmap, dc_key; 

HBITMAP bitmap up, bitmap down; 

/♦ Global declarations */ 


RECT up, down; /* Display surface areas within button */ 

static LPSTR app name; 

LPSTR field; /♦ Pointer to current caption field ♦/ 

static HANDLE instance; 

HBITMAP bitmap, bitmap key; 

static ERRPROC far * fatal; 

HWND button; 



char caption[MAXTEXTLEN]; 

/♦ For debugging: Display given DC+bitmap in center of screen ♦/ 

UINT text format; 

void show(HDC dc in) 


int width, height; /* Of entire button window */ 

{ 

HDC dc; 

dc - GetDC(NULL); 
BitBlt(dc, 300, 200, 
ReleaseDC(NULL, dc); 

} /* show */ 

100, 100, dc_in, 0, 0, SRCCOPY); 

/♦int movement; * Motion of image, up/down ♦/ 

int x_border, y_border, x, y, layer, dialog_level; 

COLORREF color_btntext; 

/* Delete a GDI object, with error check */ 
static void del(HANDLE object) 

{ 

if (IDeleteObject(object)) 

/* 3-D Pushbutton Parameters 

V 

Idefine DELIM /* Field delimiter in 3-D control string */ 

fatal("attempted to delete a GDI object Ox%lX that was " 

Idefine MOVEMENT 2 

/♦ Of button when it is pushed, */ 

•already deleted or is still selected in a DC", 

/* in units of border thickness ♦/ 

(long)(void FAR *)object); 

Idefine SHADOW OFFSET 1 

/* Additional offset of shadows of ♦/ 

} /* del */ 

/♦ 2d areas onto 3d background ♦/ 




/♦ Create a Memory DC containing a new or existing bitmap. 

/* Maximum length of button caption text */ 

monochrome or color. If a bitmap is to be created, uses global 

Idefine MAXTEXTLEN 512 


width and height values. Assumes that dc button is an active 
color window DC and that dc up is an active memory DC. ♦/ 

/♦ Standard 16 VGA Colors */ 


static void create dc with bitmap(HDC * dc out, HBITMAP * bitmap. 

Idefine COLOR BLACK 

RGB(0, 0, 0) 

BOOL in color) 

Idefine COLOR DKRED 

RGB(128, 0, 0) 

{ 

Idefine COLOR DKGREEN 

RGB(0, 128, 0) 

if (Idc out || (bitmap) 

Idefine COLOR DKYELLOW 

RGB(128, 128, 0) 

fatal("a ref arg is NULL", NULL); 

Idefine COLOR DKBLUE 

RGB(0, 0, 128) 


Idefine COLOR DKMAGENTA 

RGB(128, 0, 128) 

/* Create memory DC ♦/ 

Idefine COLOR DKCYAN 

RGB(0, 128, 128) 

*dc out - CreateCompatibleDC(in color ? dc button : dc up); 

Idefine COLOR LTGRAY 

RGB(192, 192, 192) 

if out) 

Idefine COLOR GRAY 

RGB(128, 128, 128) 

fatal("cannot create a device context", NULL); 

Idefine COLOR RED 

RGB(255, 0, 0) 

Idefine COLOR GREEN 

RGB(0, 255, 0) 

/* Create bitmap, if needed, and select into memory DC */ 

Idefine COLOR YELLOW 

RGB(255, 255, 0) 

if ((^bitmap) 

Idefine COLOR BLUE 

RGB(0, 0, 255) 

♦bitmap » CreateCompatibleBitmap(in color ? dc button : *dc out. 

Idefine COLOR MAGENTA 

RGB(255, 0, 255) 

width, height); 

Idefine COLOR CYAN 

RGB(0, 255, 255) 

if ((♦bitmap) 

Idefine COLOR WHITE 

RGB(255, 255, 255) 

fatal("cannot create a bitmap", NULL); 



SelectObject("dc out, "bitmap); 

/* This nonstandard color looks too close to black to be usable: */ 


/♦Idefine COLOR_DKGRAY 

RGB(64, 64, 64) ♦/ 

/♦ Initialize memory DC */ 

SetBkMode("dc out, TRANSPARENT); /♦ For painting text over graphics ♦/ 

/* Shadows of "floating" areas on moving areas are always gray */ 

return; 

Idefine COLOR_SHADOW 

COLOR_GRAY 

} /* create_dc_with_bitmap */ 

/* 3-D effects colors used in the <name> 3d "key" bitmap ♦/ 

/* Draw a rectangle of the given color in the given DC ♦/ 

Idefine EFF CLEAR COLOR WHITE 

static void color area(HDC dc, LPRECT lpr, COLORREF color) 

Idefine EFF 3D BKGND COLOR LTGRAY 

{ 

Idefine EFF 3D FLAT COLOR RED 

static LOGBRUSH br; 

Idefine EFF 3D ENGRAVED COLOR GREEN 

Idefine EFF~3D~RAISED COLOR BLUE 

HBRUSH brush; 

Idefine EFF 2D BKGND COLOR GRAY 

/* Create solid brush and select it into the DC */ 

Idefine EFF 2D FLAT COLOR DKRED 

br.lbStyle - BS SOLID; 

Idefine EFF 2D ENGRAVED COLOR DKGREEN 

br.lbColor - color; 

Idefine EFF 2D RAISED COLOR DKBLUE 

brush - CreateBrushIndirect(&br); 



SelectObject(dc, brush); 

/* Effects modifiers bits (reflects chars after delimiter in caption text */ 


/♦ control string) */ 


/♦ Paint the brush (pattern) color ♦/ 

typedef struct { 


/♦ (Slightly faster than the FillRect function) ♦/ 

UINT mod 2 :1 


PatBlt(dc, lpr->left, lpr->top. 

UINT mod e :1 

UINT mod”r :1 


WIDTH( 1 pr), HEIGHT(lpr), PATCOPY); 

UINT mod u :1 


/♦ Deselect and delete the brush ♦/ 

UINT mod d :1 


del(SelectObject(dc, GetStockObject(NULL BRUSH))); 

UINT pad :11 


} /* color area ♦/ 

} MOD TYPE; 



MOD TYPE modifiers; 

/* Draw a one-pixel rectangle with given 3-D shading as part of a button */ 



/* frame or sides, at the given rectangle location */ 

/♦ Raster Operation (ROP) codes for patblt() and bitblt() */ 

static void draw frame line(HDC dc, COLORREF It, COLORREF rb, LPRECT lpr) 

Idefine PATANDDEST OxOOAOOOC9L /♦ ROP code for Brush & Destination */ 

{ 

Idefine PATORDEST 0x00FA0089L /* ROP code for Brush | Destination ♦/ 

HPEN pen It, pen rb; 

Idefine MASKEDBRUSH 0x00E20746L /* ROP code for Source & Brush | ♦/ 



/* ~ Source & Destination */ 

/* Init ♦/ 

Idefine PATSRCEQ 0x00C30O6AL /* ROP code for Brush Equals Source */ 

pen It - CreatePen(PS SOLID, 1, It); 

Idefine DSTERASE 0x00220326L /* ROP code for "Source & Destination */ 

pen_rb » CreatePen(PS_SOLID, 1, rb) ; 

/* 3-D global declarations */ 

/* Draw the four sublines that make one frame line */ 

lifndef max 


MoveTo(dc, lpr->left, lpr->bottom - 2); /* Start at LB corner */ 

Idefine max(a, b) ((a) < (b) ? (b) : (a)) 

SelectObject(dc, pen_lt); 
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uniformly extending the color of a line towards the left (if it is 
horizontal) or towards the top (if it is vertical). 

The methods used for 3-D frames can also be used to draw 
the sides of pushbuttons. In the up state, the sides consist of 
two frame lines shaded white on the left and top and gray on 
the right and bottom. In the down state, the sides consist of a 
single frame line shaded gray on the left and top and light 
gray on the right and bottom (if the button is pushed too far 


in, you’ll lose the 3-D effect because there’ll be too much gray 
at the left and top). 

To highlight a control with a black border, Windows makes 
the button sides and surface smaller. But since I will be com¬ 
puting the up and down bitmaps only once (at the time the 
dialog box is created), I have arranged for all button com¬ 
ponents, including frames and borders, to be drawn at fixed 
locations inside the button window. It is worth noting that the 


Listing 2 continued 


LineTo(dc, lpr->left, lpr->top); /* L edge */ 

/* OR with Light Gray/Black checkerboard to make the picture appear */ 

LineTojdc, lpr->right - 1, lpr->top); /* T edge */ 

/* lighter again with gray dots */ 

SelectObject(dc, pen rb); 

gray bitmap - LoadBitmap(instance, "gray brush"); 

LineTo(dc, lpr->right - 1, lpr->bottom - 1); /* R edge */ 

if (Igray bitmap) 

LineTojdc, lpr->left - 1, 1pr->bottom - 1); /* B edge */ 

fatal("gray brush bitmap could not be loaded", NULL); 
brush - CreatePatternBrush(gray bitmap); 

/* Done */ 

SelectObject(dc, brush); 

SelectObject(dc, GetStockObject(BLACK PEN)); 

PatBlt(dc, lpr->left, lpr->top, WIDTH(lpr), HEIGHT(lpr), 

del(pen It); del(pen rb); 

PATORDEST /* P | D */); 

} /* draw_frame_line */ 

SelectObject(dc, GetStockObject(WHITE_BRUSH)); 
del(brush); 

/* Draw a 3-D button frame at the given rectangle location on up */ 

del(gray bitmap); 

/* and down bitmaps (the rect is shrunk as a side effect) */ 

} /* gray area */ 

static void draw 3d frame(LPRECT lpr) 


{ 

/* Paint a given bitmap into the given button window dc, */ 

draw frame line(dc up, COLOR WHITE, COLOR GRAY, lpr); 

/* which is assumed to have a compatible bitmap already selected. */ 

draw frame linejdc down, COLOR WHITE, COLOR GRAY, lpr); 

/* (See Programing Windows, Petzold, 2nd Ed, p. 621, for a more */ 

InflateRect(lpr, -1, -1); 

/* general version) */ 

draw frame linejdc up, COLOR LTGRAY, COLOR LTGRAY, lpr); 

static void paint bitmap(HDC dc, HBITMAP bitmap) 

draw frame linejdc down, COLOR LTGRAY, COLOR LTGRAY, lpr); 

{ 

InflateRect(lpr, -1, -1); 

HDC dc mem; 

draw frame linejdc up, COLOR GRAY, COLOR WHITE, lpr); 
draw frame'llne(dc down, COLOR GRAY, COLOR WHITE, lpr); 

BITMAP bm; 

InflateRect(lpr, -1, -1); 

dc mem - CreateCompatibleDC(dc); 

} /* draw_3d_frame */ 

if (ldcjnem) 

fatal("cannot create a device context", NULL); 

/* Draw a two-pixel frame (the inner line is just skipped) around a */ 

SelectObject(dc mem, bitmap); 

/* button at the given rectangle location on up and down bitmaps */ 

GetObject(bitmap, sizeof(BITMAP), (LPSTR)&bm); 

/* (the rect is shrunk as a side effect). */ 

BitBlt(dc, 0, 0, bm.bmWidth, bm.bmHeight, 

/* The actual thickness of this "default button" frame is decided later, */ 

dc mem, 0, 0, SRCCOPY); 

/* at actual button painting time. */ 

DeleteDC(dc mem); 

static void draw frame(LPRECT lpr) 

{ 

draw frame line(dc up, COLOR BLACK, COLOR BLACK, lpr); 

} /* paint_bitmap */ 

/* Return a temporary rectangle representing the location of the */ 

draw frame linejdc down, COLOR BLACK, COLOR BLACK, lpr); 

/* extra outer "default" frame line on a given 3-D button */ 

InflateRect(lpr, -1, -1); 

static LPRECT default frame of(HWND button) 

draw frame linejdc up, COLOR BUCK, COLOR BUCK, lpr); 

{ 

draw frame linejdc down, COLOR BLACK, COLOR BUCK, lpr); 

static RECT surface; 

InflateRect(lpr, -1, -1); 

} /* draw frame */ 

int frame; 

GetClientRect(button, (surface); 

/* Draw the sides of a 3-D button at the given rectangle location on up */ 

frame = (short)GetProp(button, "3Df ") ; 

/* and down bitmaps (the rectangles are shrunk, and the button surface */ 

InflateRect(&surface, - frame, - frame); 

/* is painted light gray as side effects) */ 

return (surface; 

static void draw sides(LPRECT lp up, LPRECT lp down) 

{ 

/* Up state */ 

} /* default_frame_of */ 

/* Return a temporary rectangle representing the surface (display) */ 

draw frame line(dc up, COLOR WHITE, COLOR GRAY, lp up); 

/* area of a given 3-D button */ 

InflateRect(lp up, -1, -1); 

static LPRECT surface of(HWND button, BOOL down) 

draw frame line(dc up, COLOR WHITE, COLOR GRAY, lp up); 

{ 

InflateRect(lp_up, -1, -1); 

LPRECT lpsurface; 

/* Default It gray color */ 

lpsurface » default frame of(button); 

color area(dc up, lp up, COLOR LTGRAY); 

InflateRect(lpsurface, - 4, -4); 

color_areajdc_down, lp_down, C0L0R_LTGRAY) ; 

if (down) 

OffsetRect(lpsurface, 2, 2); 

/* Down state */ 

return lpsurface; 

SetRect(lp down, lp down->left, lp down->top, 

} /* surface of */ 

lp down->right + 1, lp down->bottom +1); /* Locate shadow */ 


draw frame line(dc down, COLOR SHADOW, COLOR BLACK, lp down); 

/* Locate the next field and mark the end of the current field string: */ 

SetRect(lp down, 

/* change next 3-D delimiter to a NUL, so a field in a caption string */ 

lp down->left + MOVEMENT ♦ 2, lp down->top + MOVEMENT + 2, 

/* can be used as a NUL-delimited string */ 

lp down->right - 1, lp down->bottom - 1); /* Locate surface */ 

BOOL marked; 

} /* draw_sides */ 

LPSTR cl; /* Pointer to start of next field (or, if none, to NUL) */ 
static void mark eos(void) 

/* Gray the picture inside the rectangle in the given 3-D button, */ 

{ 

/* to indicate that this control is disabled */ 

marked - FALSE; 

static void gray area(HDC dc, LPRECT lpr) 

for (cl » field; *cl; cl++) 

{ 

if (*cl EQ DELIM) 

HBRUSH brush; 

{ 

HBITMAP gray_bitmap; 

marked ■ TRUE; 

*cl - NUL; 

/* AND with solid Light Gray brush: Makes colors darker */ 

break; 

SelectObject(dc, GetStockObject(LTGRAY BRUSH)); 

} /* Found delimiter */ 

PatBlt(dc, lpr->left, lpr->top, WIDTH(lpr), HEIGHT(lpr), 

PATANDDEST /* P & D */); 

) /* mark_eos */ 

/* Undo the effect of the last call to mark_eos (these must be called */ 
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user can click on any part of a 3-D button, including its 3-D 
frame, to depress it. 

To summarize, then, there are eight different effects to 
simulate (both for text and graphics). Figure 1 shows a side 
view of how all eight effects work. 

Using the 3-D Functions 

The program btn.exe displays a single dialog box contain¬ 
ing a number of different kinds of pushbuttons — some with 


engraved or raised text, some with graphics, some with both 
text and graphics. The possibilities in your own programs are 
limited only by your imagination. 

Listing 1 (j btn_fncs.h) contains the header file for the 3-D 
button functions, and Listing 2 (btn_fncs.c) contains the com¬ 
plete source code for the functions themselves. Take the fol¬ 
lowing steps to use the 3-D button functions: 

1. Call init_3d() at the beginning of your program and call 
term_3d() at the end of your program. 



/* in non-nested pairs) and skip to the next field */ 
static void unmark_eos(void) 

{ 

if (marked) 

*cl - DELIM; 
field * cl; 

} /* unmark_eos */ 

/* Text Display Part */ 

/* Draw a text image on a given DC+bitmap (text_format is global) */ 
static void draw_text_effect(HDC dc, LPRECT lpr, 

COLORREF color, int offset) 

{ 

OffsetRect(lpr, offset * x_border, offset * y_border); 

SetTextColor(dc, col or); 

DrawText(dc, field, -1, lpr, text_format); 

OffsetRect(lpr, - offset * xborder, - offset * y_border); 

) /* draw_text effect */ 

/* Draw a single text image on up and down bitmaps, given an offset (in */ 

/* pixels) of the image from its normal position (used to create highlights 

* and shadows) and the amount of movement (in border thicknesses) between 

* the up and down states */ 

static void draw_text_image(COLORREF color, int offset) 

{ 

draw_text_effect(dc_up, &up, color, offset); 
if (modifiers.mod_2) /* This text is 2-D (it doesn't move) */ 

{ 

draw text_effect(dc_down, &down, C0L0R_SHAD0W, 

offset + SHAD0W_0FFSET); /* Shadow on 3-D surface */ 
draw_text_effect(dc_down, &down, color, 

offset - MOVEMENT); /* Remove normal 3-D movement */ 

} 

else 

draw_text_effect(dc_down, idown, color, offset); 

} /* draw_text_image */ 

/* Draw 3-D text */ 
static void draw_text(void) 

{ 

/* Set up for text drawing */ 

text_format - DT_N0CLIP | DT_SINGLELINE | DT_TABSTOP | DT_CENTER; 

if (modifiers.mod_u) /* Place this text at top */ 
text_format |« DT_T0P; 

else if (modifiers.mod_d) /* Place this text at bottom */ 
text_format |- DT_B0TT0M; 

else 

text_format |- DT_VCENTER; /* Default is vertically centered */ 
if (modifiers.mod r) /* Raised */ 


draw_text_image(COLOR_WHITE, -1); 
draw_text_image(COLOR_GRAY, 1); 

} 

if (modifiers.mode) /* Engraved Text */ 
draw_text_image(COLOR_WHITE, 1); 
draw_text_image(color_btntext, 0); 

} /* draw”text */ 

/* Graphics Display Part */ 


/* Highlight */ 

/* Shadow */ 


/* Highlight */ 

/* Text Itself */ 


/* Move and draw a given effect DC+bitmap, transparently and with a */ 

/* given offset, onto the given up or down DC+bitmap */ 

static void draw_mask(HDC dc_dest, LPRECT lprdest, HOC dc_effect, HDC dcbw, 
int offset) 

{ 

/* Turn to black the effect areas on the dest DC+bitmap */ 
BitBlt(dc_dest,lpr dest->left + offset * x_border, 
lpr_dest->top + offset * y_border, 
width, height, 

dc_bw, 0, 0, DSTERASE /* ~S & D */); 

/* Copy (OR) the effect DC+bitmap to the dest DC+bitmap */ 
BitBlt(dc_dest, lpr_dest->left + offset * x_border, 
lpr_dest->top + offset * y_border, 
width, height, 


dc_effect, 0, 0, SRCPAINT /* S | D */); 

} /* draw mask •/ 

/* Draw one 3-D effect: Mask the bitmap and copy the result 

* to the up/down DCs/bitmaps, changing colors and positions 

* to simulate illumination, shading, shadows, and movement. 

* Uses global width and height. */ 

static void draw_effeet(COLORREF effect color, 

BRIGHTNESS TYPE brightness, int offset, M0VE_TYPE movement) 

{ 

HDC dc effect; 

HBITMAP bitmap_effect; 

HBRUSH brush;” 

HDC dc_bw; 

HBITMAP bitmap_bw; 

/* Note: This assumes that the effect color is a COLORREF, not a 

* bitmap color; otherwise... 

* we would need to do a color translation using the color table 

* stored inside the given bitmap, which requires getting the GDI 

* segment number, somehow constructing a pointer to the bitmap 

* (which is in GDI's default local heap), then locating the 

* RGBQUAD color table. Windows has no documented way to do this. */ 

/* Create a color DC+bitmap for generating the 3-D effect areas */ 
bitmap_effect - NULL; 

create_dc_with_bitmap(&dc_effect, &bitmap_effect, TRUE); 

/* Add a solid brush of the given effect color */ 
brush ■ CreateSol idBrush(effect_color); 

SelectObject(dc_effect, brush); 

/* Make only the effects areas white */ 

BitBlt(dc_effect, 0, 0, width, height, dc_key, 0, 0, PATSRCEQ); 

/* Convert effects to monochrome (making all colors other than white */ 
/* turn into black) */ 
bitmap_bw * NULL; 

create_dc_with_bitmap(&dc_bw, &bitmap_bw, FALSE); 

BitBlt(dc_bw, 0, 0, width, height, dc_effect, 0, 0, SRCCOPY); 

/* Copy the user DC+bitmap to the effect DC+bitmap */ 

BitBlt(dc_effect, 0, 0, width, height, dc_bitmap, 0, 0, SRCCOPY); 

/* Change the brightness of the effects areas */ 
switch (brightness) 

{ 

case SHADOW: 

SelectObject(dc_effeet, GetStockObject(GRAY_BRUSH)); 
BitBlt(dc_effect, 0, 0, width, height, 
dc_bw, 0,"0, MASKEDBRUSH /* S & P | ~S & D */); 
break; 

case DARKER: 

SelectObject(dc_effeet, GetStockObject(LTGRAY_BRUSH)); 

PatBlt(dc_effect, 0, 0, width, height, PATANDDEST /* P & D */); 
break; 

case SAME_C0L0R: 
break; 

case BRIGHTER: 

SelectObject(dc effect, GetStockObject(LTGRAY_BRUSH)); 

PatBlt(dc_effeet, 0, 0, width, height, PATORDEST /* P | D */); 
break; 
default: 

fatal("no such case", NULL); 

) /* Switch on brightness */ 

/* Turn to black the non-effect areas on the effect DC+bitmap */ 
BitBlt(dc_effect, 0, 0, width, height, 

dc_bw, 0, 0, SRCAND /* S & D */); 

/* Copy the effect DC+bitmap transparently onto the up and down */ 

/* DCs+bitmaps */ 
if (brightness NE SHADOW) 

draw_mask(dc_up, &up, dc_effect, dc_bw, offset); 
draw mask(dc_down, &down, dc_effect, dc_bw, offset + (int)movement); 
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Listing 2 continued 


/* Cleanup */ 
DeleteDC(dc_bw); 
del(bitmap_bw); 

DeleteDC(dc_effeet); 
del(bitmap_effeet); 
del(brush); 

) /* draw_effect */ 


/* Draw given bitmap on up and down DCs+bitmaps according to given */ 

/* "key" bitmap */ 

static void draw_bitmap(void) 

( 

char key_name[IDLEN]; /* Name of "key" bitmap */ 


/* Table of painted 3-D graphics effects */ 
typedef struct 
{ 


COLORREF 

BRIGHTNESS_T 

int 

M0VE_TYPE 

) 

EFFECT_TYPE * 
static EFFECT_TYPE 
{ 

/* 3-D (Movi 


effect_color; 

brightness; 

offset; 

movement; 

EFFECT_TYPE; 

e; 

effect [] = 
effects */ 


/* 3-D background area */ 

{EFF_3D_BK G ND, SAME_C0L0R, 0, MOVE), 

/* Shadows from 2-D areas onto 3-D background */ 
{EFF_2D_FLAT, SHADOW, SHAD0W_0FFSET, MOVE), 
(EFF_2D_RAISED, SHADOW, SHADOW_OFFSET, MOVE), 
(EFF_2D_ENGRAVED, SHADOW, SHAD0W_0FFSET, MOVE), 

/* Flat areas */ 

(EFF_3D_FLAT, SAME_C0L0R, 0, MOVE), 

/* Engraved areas */ 

{EFF_3D_ENGRAVED, BRIGHTER, 1, MOVE), 
(EFF_3D_ENGRAVED, SAME_C0L0R, 0, MOVE), 

/* Raised (embossed) areas */ 

(EFF_3D_RAISED, BRIGHTER, -1, MOVE). 
(EFF_3D_RAISED, DARKER, 1, MOVE), 

{EFF3DRAISED, SAME_C0L0R, 0, MOVE), 


/* 2-D (Floating, non-moving) effects */ 

(EFF_2D_BKGND, SAME_C0L0R, 0, N0_M0VE), 
(EFF_2D_FLAT, SAME_C0L0R, 0, N0_M0VE), 
(EFF_2D_ENGRAVED, BRIGHTER, 1, NOMOVE), 
(EFF_2D_ENGRAVED, SAME_COLOR, 0, N0_M0VE), 
(EFF_2D_RAISED, BRIGHTER, -1, NO_MOVE), 
{EFF2DRAISED, DARKER, 1, N0_M0VE), 
(EFF_2D_RAISED, SAME_C0L0R, 0, NO_MOVE), 

/* End */ 

(0, SAME_C0L0R, 0, END) 


/* Read bitmap resource from the .EXE file into its own DC */ 
bitmap « LoadBitmap(instance, field); 
if ([bitmap) 

fatal("bitmap %s could not be found", (long)field); 
create_dc_with_bitmap(&dc_bitmap, &bitmap, TRUE); 

/* Same for the "key" bitmap <name>_3d */ 
wsprintf(key_name, "%s_3d", field); 
bitmap_key ■ LoadBitmap(instance, key_name); 
if (!bitmap_key) 
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Listing 2 continued 


fatal (“\ 11 key\“ bitmap %s could not be found", 

(long)(void FAR *)key_name); 
create_dc_with_bitmap(&dc_key, &bitmap_key, TRUE); 

/* Simulate each 3-D effect */ 

for (e = effect; e->movement NE END; e++) 

draw_effect(e->effect_color, e->brightness, 
e->offset, e->movement); 

/* Delete the loaded bitmap and its DC, same for key */ 

DeleteDC(dc_bitmap); 

dc_bitmap = NULL; 

del(bitmap); 

bitmap * NULL; 

DeleteDC(dc_key); 
dc_key = NULL; 
del(bitmap_key); 
bitmap_key = NULL; 

) /* draw_bitmap */ 

/* Draw current field on up and down views */ 
static void draw_field(void) 

( 

if (‘field NE DELIM) 

fatal("3-D button format invalid: %s“, 

(long)(void FAR *)caption); 
field++; /* Skip delimiter */ 

/* Look for modifier letters */ 

‘(short *)&modifiers = 0; 
for (; ‘field; field++) 

( 

switch (‘field) 

( /* Modifiers: */ 

case '2': modifiers.mod_2 = 1; continue;/* 2-D (Floating) */ 

case 'e': modifiers.mod_e = 1; continue;/* Engraved */ 

case 'r': modifiers.mod_r = 1; continue;/* Raised (Embossed) */ 

case V: modifiers.mod_u = 1; continue;/* Up (text at top) */ 

case ‘d': modifiers.mod_d = 1; continue;/* Down (text at bottom) */ 
} /* Switch on letter */ 
break; 

) /* Loop on modifier letters */ 
if (!*field) 

fatal("3-D button format invalid: %s", 

(long)(void FAR *)caption); 

/* Switch on field letter and locate to and delimit its string */ 

/* subfield, if any */ 
mark_eos(); /* Delimit string */ 
switch (*field++) 

{ 

case 1 f 1 : /* Frame (handled already) */ 
break; 

case 't': /* Text */ 
draw_text(); 
break; 

case 'b': /* Bitmap, with effects colors specified in */ 

/* "key" bitmap <name>_3d */ 
if (‘(short *)&modifiers NE 0) 

fatal("3-D button format invalid: %s“, 

(long)(void FAR *)caption); 
draw_bitmap(); 
break; 

default: 

fatal("3-D button format invalid: %s", 

(long)(void FAR *)caption); 

} /* Switch on field letter */ 
unmark_eos(); 

) /* draw_field */ 

/* Draw the complete up and down bitmaps for a given 3-D button 

* at dialog initialization time (text caption is global and has 

* already been read) */ 

static void draw_3d_button(HWND button_arg) 


2. Add three cases and function calls 
to each of your dialog box procedures, 
as shown in Figure 2 (you can combine 
these into one function call to be in¬ 
serted before the switch statement if 
you wish; this would be particularly 
helpful if you have many dialog boxes 
in your application). 

3. In your .rc file (or in your 
resource editor environment), declare 
your 3-D buttons with the 
BS_OUNERDRAU attribute. Assign a child 
identifier to your 3-D buttons just as 
you usually do, for use in the I^COM¬ 
MAND message. 

4. In your . rc file give each of your 
buttons a caption (title) string contain¬ 
ing 3-D field specifications defined as 
shown in Figure 3. For example, 

@f@bpicture 

means “draw a 3-D frame, then draw 
the graphics described by the bitmap 
named 'picture' and bitmap named 'pic- 
ture_3d'.” The picture_3d bitmap is a 
key showing what 3-D effects to do 
where. 

5. Add the bitmaps and key bitmaps 
named in your field specifications to 
your .rc file. You can have any com¬ 
bination of text or bitmaps on a single 
button surface, but if you specify a 3-D 
frame the @f must come first. 

You can create your bitmaps using 
any bitmap editor. It is easiest to create 
the base bitmap first, then copy it to 
create the key bitmap. Then you edit 
your key bitmap, changing the colors 
according to the key shown in Figure 3. 

If you specify the button first, make 
the bitmaps for it 8 pixels less in both 
width and height (14 pixels if you in¬ 
clude a 3-D frame). If you specify the 
bitmaps first, make the button for them 
8 pixels greater in width and height (14 
if you include a 3-D frame). That’s all 
there is to it. It's easy to do once you 
play with it a little. Figure 4 shows an 
example of the output from btn.exe. □ 
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Listing 2 continued 


{ 

UINT style; 

/* Make button window global */ 
button = button_arg; 

/* If this button has already been analyzed, error */ 
if (GetProp(button, “3Du“)) 

fatalC'a button already has 3-D properties %s at a call " 
"to draw_3d_button", (long)(void FAR *)caption); 
/* Disable double-clicking (makes no sense for buttons anyway) */ 
style = GetClassWord(button, GCW_STYLE); 

SetClassWord(button, GCW_STYLE, style & ~CS_DBICLKS); 

/* Start drawing at the button border */ 

GetClientRect(button, &up); 
width = WIDTH(&up); /* Global */ 
height = HEIGHT(&up); /* Global */ 

/* Create a DC that will be used for color information */ 
dc_button = GetDC(button); /* Global */ 

/* Create Up and Down memory device contexts and bitmaps and 

* store the bitmaps as window properties of the button */ 
bitmap_up ■ bitmap_down = NULL; 
create_dc_with_bitmap(&dc_up, &bitmap_up, TRUE); 
create_dc_with_bitmap(&dc_down, &bitmap_down, TRUE); 
SetProp(button, “3Du", bitmap_up); 

SetProp(button, “3Dd”, bitmap_down); 

/* If requested, draw a 3-D frame (<delim>f must come first) */ 
if (caption[l] EQ 1 f 1 ) 

draw_3d_frame(&up); 

/* store offset to outermost “default" frame as a button property */ 
SetProp(button, "3Df", (HANDLE)(up.top)); /* Frame thickness */ 

/* Draw a black button frame 2 pixels thick (will be thinned to 

* one pixel when the button does not have the input focus, when 

* button is painted) */ 
draw_frame(&up); 

/* Split the drawing rectangle into two (for up and down states) */ 
CopyRect(&down, &up); 

/* Draw the button sides */ 
draw_sides(&up, &down); 

/* Here begins the button surface; record its height and width as 

* global variables */ 

width = WIDTH(&up); /* Global */ 
height = HEIGHT(&up); /* Global */ 

/* Draw each field in the button caption (title) text */ 
for (field = caption; *field;) 
draw_field(); 

/* Free all GDI objects except the up and down bitmaps */ 
DeleteDC(dc_up); 
dc_up = NULL; 

DeleteDC(dc_down); 
dc_down * NULL; 

ReleaseDC(button, dc_button); 
button = NULL; 
dc_button = NULL; 

} /* draw_3d_button */ 

/* Overall 3-D initializing and termination */ 

/* Initialize or terminate a single 3-D button */ 

FARPROC for_each_chi 1 di; 

static BOOL CALLBACK for_each_child(HWND child, LPARAM IParam) 
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Listing 2 


continued 


( 

if (IParam EQ 0) 

{ 

/* Initialize a 3-D button */ 


/* If this child window is not a pushbutton, ignore it */ 
GetClassName(child, caption, MAXTEXTLEN); 

If (STRCMP(caption, "Button")) 

return TRUE; /* Continue scanning */ 

/* If the caption text starts with the 3-D field delimiter, 

* indicating that this is a 3-D button, analyze the fields, 

* and construct the up and down bitmaps as window properties */ 
GetWindowText(chi 1d, caption, MAXTEXTLEN); 

if (caption[0] EQ DELIM) 

draw_3d_button(child); 

} /* Initializing */ 

else 

{ 

/* Terminate a 3-D button */ 

HBITMAP bitmap; 

/* Free all memory, if any, used by this control */ 
bitmap = RemoveProp(child, "3Du"); 
if (bitmap) 

del(bitmap); 

bitmap = RemoveProp(child, "3Dd"); 
if (bitmap) 

del(bitmap); 

RemoveProp(child, "3Ds"); 

RemoveProp(child, "3Df"); 

} /* Terminating */ 
return TRUE; /* Continue scanning */ 

} /* for_each_child */ 

/* Initialize or terminate all 3-D buttons in a dialog box */ 

/* (call from WM_INITDIAL0G and WM_DESTR0Y) */ 
void scan_3d_buttons(HWND dig, LPARAM pass) 

f 

/* Scan all child windows */ 

for_each_childi = MakeProcInstance((FARPROC)for_each_child, instance); 
EnumChildWindows(dlg, (WNDENUMPROC)for_each_childi, pass); 
FreeProcInstance(for_each_chi1di); 

} /* scan_3d_buttons */ 

/* Initialize 3-D button facility (call from start of application) */ 
void init_3d(LPSTR app_namel, HANDLE instancel, ERRPROC fatal 1) 

{ 

app_name = app_namel; 
instance = instancel; 
fatal = fatal 1; 

x_border = GetSystemMetrics(SM_CXBORDER); 
y_border = GetSystemMetrics(SM CYBORDER); 
color_btntext = GetSysColor(COLOR_BTNTEXT); 

} /* init_3d */ 

/* Terminate 3-D button facility (call from end of application) */ 
void end_3d(void) 

{ 

/* Delete any temporary objects in existence */ 
if (dc_up) DeleteDC(dc_up); 

if (dc_down) DeleteDC(dc_down); 

if (dc_button) ReleaseDC(button, dc_button); 
if (dc_bitmap) DeleteDC(dc_bitmap); 
if (bitmap) del(bitmap); 

if (dc_key) DeleteDC(dc_key); 

if (bitmap_key) del(bitmap_key); 

} /* endjd */ 

/* Paint a 3-D button in a given new state (called by a dialog box */ 

/* WM_DRAWITEM message on behalf of a single button in the box) */ 
void paint_3d button(DWORD IParam) 

{ 

LPDRAWITEMSTRUCT Ipdi; 

HWND button; 

UINT new_state; 

HBITMAP bitmap_up, bitmap_down; 

LPRECT lp_surface; 

C0L0RREF color_window; 

lpdi = (LPDRAWITEMSTRUCT)IParam; 

button = lpdi->hwndltem; 

bitmap_up = (HBITMAP)GetProp(button, "3Du"); 

bitmap_down = (HBITMAP)GetProp(button, "3Dd"); 

new_state = lpdi->itemState; 

color_window = GetSysColor(COLOR WINDOW); 

/* If this owner-draw control is NOT a 3-D button, error */ 
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Listing 2 continued 


if (!bitmap_up) 

fatal("a control marked in the .RC file as Owner-Draw M 
"has no 3-D caption", NULL); 

/* Paint up or down bitmap (according to selection state) onto */ 

/* the 3-D button */ 
if (new_state & ODS_SELECTED) 

paint_bitmap(lpdi->hDC, bitmap_down); 

else 

paint_bitmap(1pdi->hDC, bitmap_up); 

/* If the button is disabled, gray its surface */ 
if (new_state & ODS_DISABLED) 
gray_area(1pd i ->hDC, 

surface_of(button, new_state & ODS_SELECTED)); 

/* Thicken the frame when the button has input focus */ 
lp_surface = default frame of(button); 
if (new_state & 0DS_F0CUS)“ 

draw_frame_line(lpdi->hDC, COLORJLACK, COLORJLACK, lp_surface); 

else 

draw_frame_line(lpdi->hDC, color_window, color_window, lp_surface); 
/* Focus rectangles frequently don't Took very good on buttons 

* having 3-D graphics; in any case, you can tell if 

* the button has the input focus if the border around it is 

* thick. But you can use this code to draw a focus rectangle 

* if you wish. */ 

#ifdef JKJ 

if (new_state & ODS FOCUS) 

{ 

lp_surface = surface_of(button, new_state & ODS_SELECTED); 
InflateRect(lp surface, 

- WIDTH(lp_surface) / 8, - HEIGHT(lp_surface) / 8); 
DrawFocusRect(1pdi->hDC, 1p_surface); 

} /* Button has focus */ 

#endif 

} /* pa1nt_3d_button */ 

/* End of File */ 


Figure 3 Syntax for 3_D button specifications 

@f 

3-D Frame (must come first). 

@b<name> 

Draw named bitmap with key bitmap. 

@t<text string> 

Draw text string. 

@<modifiers>t<text string> 

Draw text string. 

The text modifiers are: 

2 

2-D (Floating) Text 

e 

Engraved 

r 

Raised (Embossed) 

u 

Up (At the Top) 

d 

Down (At the Bottom) 

Each bitmap has a corresponding “key’’ bitmap called <name>_3d, where 
<name> is the name of the bitmap specified with the “@b” syntax. 

In this key bitmap specific colors indicate the 3-D effects, as follows: 

Key Colors 

Light Gray 

Background that moves with button. 

Red 

Flat areas that move. 

Green 

Engraved areas that move. 

Blue 

Raised (Embossed) areas that move. 

Gray 

Background that “floats." 

Dark Red 

Flat areas that float. 

Dark Green 

Engraved areas that float. 

Dark Blue 

Raised areas that float. 

White 

Transparent (clear) areas. 
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Paul Bonneau 


Send questions to Paul via Internet 
as paul@rdpub.com-, 
from CompuServe: 

>INTERNET:pau l @rdpub. com-, 
or in care of this magazine at: 

1601 W. 23rd St., Suite 200 
Lawrence, KS 66046-2743. 


Multi-Font Edit Controls 


Q l very much enjoy your discussions of the byways and oddities of Windows 
programming and wonder if you can help me with the following problem. 

As part of a scientific program, I need some way of combining characters from 
the symbol font with characters from the standard font. I can see no way of doing 
this without subclassing the control and just about rewriting it. Is there a simpler 
way? 

I am considering providing a supplementary button to the control that gives ac¬ 
cess to the symbol characters to be selected and inserted into the control. That still 
leaves the problem of the control itself. 

With many thanks, 

Cyril Chapman 
Dept, of Paediatrics, 
University of Auckland 

A I assume you are referring to edit controls. Mixing characters from different 
fonts is functionality usually found in rich text editors. The problem with using 
an edit control is that it does not store any per-character information other than the 
8-bit code of the character itself. A rich text editor, on the other hand, associates 
attributes with each character in the text stream. 

If you do not have to use all 256 characters from your standard font, you may be 
able to remap unused character positions into symbol font characters. The problem 
with this approach is that it means capturing the output from the edit control (the 
actual calls to Windows functions that output the text) and providing your own 
output routines using mixed font characters. But this approach is a lot easier than 
writing your own rich text edit control (I don't think it's possible to force the Win¬ 
dows edit control to do what you want by subclassing it). 

In the June 1992 issue of this magazine, Timothy Adams presented an article 
entitled "Intercepting DLL Function Calls" that demonstrated a technique for inter¬ 
cepting calls to Windows functions. His idea is to install a jump instruction at the 
beginning of the routine he wants to "hook." The jump gives control to a hook 
function. Before installing the jump, he preserves the original code so that he can 
restore it when he removes the jump later. 

You can use this technique to hook three essential text routines used by the 
Windows edit control: GetTextMetrics(), GetCharUidth() , and ExtTextOut(). At 
initialization and each time the edit control receives a WM_SETFONT message, it calls 
GetTextMetrics() and GetCharUidthf) to obtain vertical size and per-character 
horizontal size information. These values are stored by the edit control and used 
when calculating character placements. To output the text to the screen, the edit 
control calls ExtTextOut(). 


Paul Bonneau is a Software Design Engineer at a major software firm. He was a 
developer of HyperChem, a molecular modeling system marketed by Autodesk. 





















Listing 1 symbase.h - Interface to hook 
framework for hooks 


/* symbase.h */ 

/* — Interface to hook framework for hooks. */ 

I *****************************************************j 

typedef struct 

{ 

HTASK htsk; /* Client task handle. */ 

HFONT hfnt; /* Font to mix. */ 

} CDS, FAR * LPCDS; /* Client Data Struct. */ 


typedef struct 

{ 

FARPROC lpfnOrig; 
BYTE bJump; 

FARPROC lpfnHook; 
BYTE rgbCode[5]; 

) HKS; 


/* Function being hooked. */ 
/* Far jump instruction. */ 
/* Hook proc. */ 

/* Code to remember. */ 

/* HooK Structure. */ 


LPCDS LpcdsGetCur(void); 


/* Hook out (or restore) the given function. */ 

Idefine HookHks(phks, fHook) \ 

MemoryWrite(SELECTOROF((phks)->lpfnOrig), \ 

OFFSETOF((phks)->lpfnOrig), \ 

(fHook) ? &(phks)->bJump : (phks)->rgbCode, \ 

sizeof (phks)->rgbCode) 


/* End of File */ 


Listing 2 symbase.c — Framework to support 
Windows function hooks 


j*****************************************************j 

/* symbase.c */ 
/* — Framework to support Windows function hooks. */ 
^★★***************************************************^ 


linclude <windows.h> 
linclude <windowsx.h> 

#include <toolhelp.h> 
linclude "symbase.h" 
linclude "symhook.h 11 
linclude "symdll.h" 

/* Private prototypes. */ 

BOOL CALLBACK FNotifyProc(WORD, NFYLOADSEG FAR *); 
int CALLBACK LibMain(HINSTANCE, WORD, WORD, LPSTR); 
int CALLBACK WEP(int); 


/* Set or remove all hooks. */ 

Idefine SetAllHooks(fHook) \ 

{ \ 

HKS * phks; \ 

for (phks * rghks; phks->lpfnOrig; phks++) \ 

HookHks(phks, (fHook)); \ 

) 


HTASK htskReg; 

LPCDS lrgcds; 
int ccds; 

int ccdsClient; 

Idefine dcds 10 

int CALLBACK 

LibMain(HINSTANCE hinsThis, WORD ds, WORD cbHeap, 

LPSTR lsz) 

y*****************************************************y 
/* -- Entry point during initialization. */ 

J*****************************************************/ 


/* NotifyRegister() task. */ 
/* Client array. */ 

/* Size of array. */ 

/* Client task count. */ 

/* Allocation increment. */ 


Listing 2 continued 


{ 

HKS * phks; 

/* Save entry code of functions to hook. */ 
for (phks = rghks; phks->lpfnOrig; phks++) 
MemoryRead(SELECTOROF(phks->lpfnOrig), 

OFFSETOF(phks->lpfnOrig), phks->rgbCode, 
sizeof phks->rgbCode); 

return 1; 

) 

int CALLBACK 
WEP(int wExitCode) 

/★**★*★★***★★***★****★★★★***★****★*★*******★**★***★*** j 

/* -- Exit proc. */ 

/* -- No need to free global memory, Windows will. */ 

j******★★*★***********★***★*★**★★**★★****★★★★★★*******j 

{ 

SetAl1 Hooks(FALSE); 
if (htskReg) 

Noti fyllnRegi ster(htskReg); 
return 1; 

) 

BOOL WINAPI 

FStartFontMix(HFONT hfnt) 

^*****************************************************y 
/* -- Called by a client when it wants mixed font. */ 

/*****************************************************j 

{ 

int icds, icdsT; 

HTASK htsk = GetCurrentTask(); 

/* Look for an empty slot in the task array and */ 
/* make sure task is not already known. */ 
for (icds ■ ccds, icdsT ■ 0; icdsT < ccds; icdsT++) 
( 

if (llrgcds[icdsT].htsk && icds ■■ ccds) 
icds = icdsT; 

if (1rgcds[icdsT].htsk == htsk) 
return FALSE; 

1 

/* If we didn't find one, grow the array. */ 
if (icds -- ccds) 

{ 

LPCDS IrgcdsNew; 

int cb = (ccds + dcds) * sizeof(CDS); 

if (!(IrgcdsNew = lrgcds ? GlobalReAllocPtr( 
lrgcds, cb, GHND | GMEM_SHARE) : 

GlobalA1 locPtr(GHND | GMEMJHARE, cb))) 
return FALSE; /* Out of memory. */ 

lrgcds = IrgcdsNew; 
ccds += dcds; 

) 

/* If this is the first app, install the hooks */ 

/* and toolhelp callback. */ 
if (IccdsClient) 

{ 

SetAllHooks(TRUE); 
if (!NotifyRegister(htskReg = htsk, 

(LPFNNOTIFYCALLBACK)FNotifyProc, NF_N0RMAL)) 
return FALSE; /* Give up. */ 

} 

ccdsClient++; 
lrgcds[icds].htsk = htsk; 
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My idea is to intercept these functions, check for character 
values above 127, and switch to the symbol font for each of 
those characters. The function to hook GetTextMetrics() (call 
it HookGetTextMetrics()) would return the maximum height 
of the two fonts to allow enough space on each line for 
either. Following the same naming convention, HookGetChar- 
Uidth() would return the original widths of the unmapped 


Listing 2 continued 


lrgcdsficds] .hfnt = hfnt; 
return TRUE; 

} 

void WINAPI 
StopFontMix(void) 

/* -- Called by a client when it no longer wants */ 
/* mixed font support. */ 

y*****************************************************^ 

{ 

LPCDS lpcds, lpcdsLim; 

HTASK htsk; 

if (! (1 pcds * LpcdsGetCurO)) 

return; /* Unknown task. */ 

htsk = lpcds->htsk; /* Remove from list. */ 
lpcds->htsk * NULL; 

/* Remove toolhelp callback if it was installed */ 
/* with this task. */ 
if (htskReg «« htsk) 

{ 

NotifyUnRegister(htskReg); 
htskReg = NULL; 

} 

/* If there is another client, reinstall. */ 
if (--ccdsClient) 

{ 

for (lpcds = lrgcds, lpcdsLim = lpcds + ccds; 
lpcds < lpcdsLim; lpcds++) 
if (lpcds->htsk) 

{ 

NotifyRegister(htskReg = lpcds->htsk, 

(LPFNNOTIFYCALLBACK)FNotifyProc, 
NF_N0RMAL); 
break; 

) 

) 

else 

{ 

SetAllHooks(FALSE); 

} 

) 

LPCDS 

LpcdsGetCur(void) 

^★★★★★★★★★★★★★★★*************f'************************y 

/* -- Return a pointer to the current task's entry */ 
/* in the client task list. Return NULL if task */ 

/* is unknown. */ 

^★★★★★★★★★★★★★★★★★★★★★********************************y 

{ 

HTASK htsk » GetCurrentTaskO; 

LPCDS lpcds, lpcdsLim; 

if (llrgcds) 
return NULL; 
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Listing 2 continued 


for (lpcds = Irgcds, lpcdsLim = lpcds + ccds; 

Ipcds < lpcdsLim; lpcds++) 
if (lpcds->htsk == htsk) 
return lpcds; 

return NULL; 

} 

BOOL CALLBACK 

FNotifyProc(WORD nfy, NFYLOADSEG far * lpnls) 

j***********★★*★*★★***********************************j 

/* -- Toolhelp callback. */ 

/* -- If the segment containing a hooked routine is */ 
/* being reloaded, reinstall the jump. */ 

y*****************************************************^ 

{ 

switch (nfy) 

{ 

default: 

break; 

case NFY_LOADSEG: 

{ 

HKS * phks; 

for (phks = rghks; phks->lpfnOrig; phks++) 
if (lpnls->wSelector == 

SELECTOROF(phks->lpfnOrig)) 

HookHks(phks, TRUE); 

} 

break; 

case NFY_EXITTASK: 
if (LpcdsGetCurO) 

StopFontMixO; 
break; 

} 

return FALSE; 

) 

/* End of File */ 


Listing 3 symhook.c - Hook functions 


^*****************************************************y 
/* symhook.c */ 

/* -- Hook functions. */ 

#include <windows.h> 

#include <windowsx.h> 

#include <toolhelp.h> 
finclude "symdll.h" 
finclude "symbase.h" 
fdefine DEFINE_H00K$ 
linclude "symhook.h" 

BOOL WINAPI 

HookGetTextMetri cs(HDC hdc, LPTEXTMETRIC lptxm) 
y*****************************************************y 
/* -- GetTextMetrics() hook function. */ 

/* -- Return the max of the two font metrics. */ 

y***************************************************** y 

{ 

LPCDS lpcds; 

TEXTMETRIC txm; 

HFONT hfntSav = NULL; 

BOOL fVal; 

HookHks(phksGetTextMetrics, FALSE); 


characters and the widths in the symbol font of the remapped 
characters. HookExtTextOutO would output the unmapped 
characters in the original font and the mapped ones in the 
symbol font. 

Listings 1 through 6 implement SymDII, a DLL that ex¬ 
emplifies this approach. I chose to encapsulate the hook func¬ 
tions and helper routines in a DLL because the DLL can keep 


Listing 3 continued 


if ((fVal = GetTextMetrics(hdc, lptxm)) && 
(lpcds » LpcdsGetCurO) && 

(hfntSav = SelectObject(hdc, 1pcds->hfnt))) 

( 

fVal = GetTextMetrics(hdc, Stxm); 
lptxm->tmHeight = 

max(1ptxm->tmHeight, txm.tmHeight); 
SelectObject(hdc, hfntSav); 

) 

HookHks(phksGetTextMetrics, TRUE); 
return fVal; 

) 


BOOL WINAPI 


HookGetCharWidth(HDC hdc, UINT chFirst, UINT chLim, 
LPINT Irgdx) 


/ 

/ 

/ 

/ 


* — GetCharWidth() hook function. */ 

* — Any characters above 0x80 are mapped to the */ 

* first 0x80 characters of the symbol font. */ 



( 


BOOL fVal = FALSE; 
HFONT hfntOrig = NULL; 
LPCDS lpcds; 


/* Remove hook so we can make use of */ 
/* GetCharWidth(). */ 

HookHks(phksGetCharWidth, FALSE); 


if (! (1 pcds = LpcdsGetCurO)) 

{ 

fVal = 

GetCharWidth(hdc, chFirst, chLim, Irgdx); 
goto HookGetCharWidthExit; 

) 

/* Do lower half. */ 
if (chFirst < 0x80) 

( 

UINT ch; 

ch = chLim < 0x80 ? chLim : 0x7f; 
if (!(fVal = 

GetCharWidth(hdc, chFirst, ch, Irgdx))) 
goto HookGetCharWidthExit; 

Irgdx +• ch - chFirst + 1; 
chFirst = ch + 1; 

I 

/* Do upper half. */ 
if (chLim >= 0x80) 

( 

hfntOrig = SelectObject(hdc, lpcds->hfnt); 
fVal = GetCharWidth(hdc, chFirst - 0x80, 
chLim - 0x80, Irgdx); 

) 


HookGetCharWidthExit: 
if (hfntOrig) 

SelectObject(hdc, hfntOrig); 
HookHks(phksGetCharWidth, TRUE); 
return fVal; 

} 
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track of who wants mixed font support by maintaining a list 
of client tasks. This avoids multiple levels of function hooking 
if more than one application were to intercept these func¬ 
tions. Listing 1 defines an interface to services provided by the 
DLL to the hook functions, and Listing 2 implements these ser¬ 
vices and provides other housekeeping. Listing 3 contains the 


hook functions, and Listing 4 the interface from the hooks to 
the basic services. Listing 5 contains the prototypes of the 
functions exported to the client, and Listing 6 the linker 
module definition file for the DLL. By using this file organiza¬ 
tion, only Listings 3 and 4 need be changed to build a DLL that 
hooks a different set of functions. 


Listing 3 continued 


BOOL WINAPI 

HookExtTextOut(HDC hdc, int x, int y, UINT f, 

LPRECT lprect, LPSTR lsz, UINT cch, LPINT Irgw) 

j*****************************************************J 


/* -- ExtTextOutf) hook function. */ 
/* -- Any characters above 0x80 are mapped to the */ 
/* first 0x80 characters of the symbol font. */ 
/* -- We call ExtTextOutf) for each chunk of like- */ 
/* font characters. If ET0_0PAQUE was specified, */ 
/* we clear it after the first chunk, else the */ 
/* leading chunks will get erased. */ 


^★★★★★★★★★★★★★★★★★★★★★★★■Ar***************************** j 

I 

BOOL fVal = FALSE; 

LPBYTE lpch, lpchLim; 

HFONT hfntOrig = NULL; 

UINT wTextAlignSav = 0; 

LPCDS lpcds; 

/* Remove hook so we can make use of */ 

/* ExtTextOutf). */ 

HookHksfphksExtTextOut, FALSE); 

/* If no text to output, or task is not */ 

/* known, or we can't select the client's */ 

/* font, just call the original. */ 

if (llsz || lech || Iflpcds « LpcdsGetCurf)) || 

!(hfntOrig = SelectObjectfhdc, lpcds->hfnt))) 

f 

fVal * ExtTextOutfhdc, x, y, f, lprect, lsz, cch, 
1rgw); 

goto HookExtTextOutExit; 

I 

/* Use TA_UPDATECP so we don't have to track */ 

/* where to start the next chunk. */ 

MoveToExfhdc, x, y, NULL); 
wTextAlignSav = SetTextAlign(hdc, TA_UPDATECP); 
for (lpch = lsz, lpchLim = lpch + cch; 
lpch < lpchLim;) 

( 

int cb; 

LPBYTE lpchT; 

LPBYTE lpchScan - lpch + 1; 

BOOL fClientFont * *lpch >= 0x80; 

for (; lpchScan < lpchLim; lpchScan++) 

if ((fClientFont &£. ‘lpchScan < 0x80) || 

(!fClientFont && ‘lpchScan >« 0x80)) 
break; 

cb = lpchScan - lpch; 

SelectObject(hdc, 

fClientFont ? lpcds->hfnt : hfntOrig); 
if (fClientFont) /* Map to lower 0x80. */ 
for (lpchT = lpch; lpchT < lpchScan; 
lpchT++) 

♦lpchT &= 0x7f; 

if (!ExtText0ut(hdc, 0, 0, f, lprect, lpch, cb, 

1rgw)) 

goto HookExtTextOutExit; 


if (fClientFont) /* Restore string. */ 
for (lpchT = lpch; lpchT < lpchScan; 
lpchT++) 

*1pchT |= 0x80; 

f &= ~ET0_0PAQUE; /* Only erase once. */ 
if (lrgw) /* Update cell spacing. */ 

lrgw += cb; 

lpch = lpchScan; 

) 

fVal = TRUE; 

HookExtTextOutExit: 
if (hfntOrig) 

SelectObject(hdc, hfntOrig); 
if (wTextAlignSav) 

SetTextAlign(hdc, wTextAlignSav); 
HookHksfphksExtTextOut, TRUE); 
return fVal; 

} 

/* End of File */ 
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Patching Functions with TooIHelp 

One of the problems with modifying code segments is that 
Windows can discard them. When Windows needs a code 
segment that it discarded earlier, it reloads the code from 
disk. The problem is, if you modify a code segment that is 
then discarded and later reloaded, the modifications will have 
been lost. Timothy Adams addressed this problem by fixing 
the code segments in memory, but that can lead to memory 
fragmentation. I chose instead to make use of the Toolhelp 
(Toolhelp is a library of system services that shipped with the 
Windows 3.1 SDK) NotifyRegisterf) routine. This function in¬ 
stalls a callback that gets called when, among other things, 
Windows is loading a segment into memory. If the segment 


Listing 4 symhook.h - Interface to hook functions 
for hook framework 


I ★★★★★★★★★★★★★★★★★★★★★★★*★★★★**★*★★★★★★★★★★★★★★★★★★*★★y 
/* symhook.h */ 

t* — Interface to hook functions for hook */ 

/* framework. */ 

/*****************************************************i 

/* Hook functions. */ 

BOOL WINAPI HookExtTextOut(HDC, int, int, UINT, LPRECT, 
LPSTR, UINT, LPINT); 

BOOL WINAPI HookGetCharWidth(HDC, UINT, UINT, LPINT); 
BOOL WINAPI HookGetTextMetrics(HDC, LPTEXTMETRIC); 

/* Hook data array. */ 

#i fdef DEFINE_HOOKS 
HKS rghks[] = 

{ 

{ 

(FARPROC)GetCharWidth, Oxea, 

(FARPROC)HookGetCharWidth 
), 

{ 

(FARPROC)ExtTextOut, Oxea, 

(FARPROC)HookExtTextOut 
}, 

{ 

(FARPROC)GetTextMetrics, Oxea, 

(FARPROC)HookGetTextMetrics 
). 

{ 

NULL, 0, NULL, 

) 

); 

#else /*!DEFINE_HOOKS*/ 

extern HKS rghks[]; 
fendif /*DEFINE_H00NS*/ 

/* Hook data array entries. */ 

Idefine phksGetCharWidth rghks 
Idefine phksExtTextOut (rghks + 1) 

Idefine phksGetTextMetrics (rghks + 2) 

/* End of File */ 


Listing 5 symdll.h — Client interface to symdll 


J*****************************************************I 

/* symdll.h */ 

/* — Client interface to symdll. */ 

/*****************************************************/ 
/* Exported to client. */ 

BOOL WINAPI FStartFontMix(HFONT); 

void WINAPI StopFontMix(void); 

/* End of File */ 


being loaded contains one of the functions being hooked, the 
callback can reinstall the hook. 

When NotifyRegister() calls your callback function, your 
code can access only a very limited subset of the Windows 
API. According to the SDK's online help, "typically, the notifica¬ 
tion callback function cannot use any Windows function, with 
the exception of the Tool Helper functions and PostMessage.” I 
can vouch for this from experience. Originally, I attempted to 
use AllocSelector() and PrestoChangoSelector() to get a 
writable selector alias for the code segment to hook, but the 
system became quite unstable. Fortunately, Toolhelp has a 
pair of routines, MemoryUrite() and MemoryRead(), that can 
write to or read from any global heap selector, including code 
segments. Using these routines simplifies the code, since you 
don’t have to worry about the lifetime of a selector, or about 
allocating and freeing selectors. On the other hand, there are 
some non-Toolhelp routines (in addition to PostMessagef)) 
that can be called from the callback function. Specifically, Get- 
CurrentTask() is a tiny routine that resides in a fixed code 
segment in Kernel and merely loads information from a global 
variable. It will be important to be able to call this routine 
from the callback function, as I will explain shortly. 

A far jump instruction requires five bytes of code. My Lib- 
Main () function (called when the DLL is first loaded) uses 
MemoryRead() to store the first five bytes of code for each 
function I plan to hook. The macro HookHksf) uses Memory- 
Urite() to either install a hook or replace the original code. I 
use the structure HKS (HooK Structure) to store the address of 
a function to hook (IpfnOrig), a jump instruction ( bJump ), the 
address of the hook function ( IpfnHook ), and the five bytes of 
code that I saved from the beginning of the function I plan to 
hook (rgbCode): 

typedef struct 

{ 

FARPROC IpfnOrig; 

BYTE bJump; 

FARPROC IpfnHook; 

BYTE rgbCode[5]; 

} HKS; 


Listing 6 symdll.def - Module definition file for 
mixed font DLL 


;; symdll.def 

> 1 

;; -- Module definition 

file for mixed font DLL. ;; 

LIBRARY SymDl1 


EXETYPE Windows 


CODE PRELOAD FIXED 

DATA PRELOAD SINGLE 

HEAPSIZE 0 


EXPORTS 


WEP 

@1 RESIDENTNAME 

FNotifyProc 

@2 

FStartFontMix 

@3 

HookExtTextOut 

@4 

HookGetCharWidth 

@5 

HookGetTextMetrics 

@6 

StopFontMix 

@7 
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Listing 7 symedit.c - Demo application that tricks an edit control into using two characters from the 
and the symbol font 


/★A***************************************************/ 


EndDialog(hwnd, wParam); 
return TRUE; 


/* symedit.c */ 

/* — Demo application that tricks an edit control */ 
/* into using two characters from the system font */ 
/* and the symbol font. */ 

y******************************** *********************j 

finclude <windows.h> 
finclude <windowsx.h> 
linclude "symdll.h" 
finclude "symedit.h" 

BOOL CALLBACK FDlgProc(HWND, UINT, WPARAM. LPARAM); 
HFONT hfntSym; /* Symbol font. */ 
int PASCAL 

WinMain(HINSTANCE hins, HINSTANCE hinsPrev, LPSTR lsz, 
int wShow) 

/***************************************************** f 
/* -- Entry point. */ 

^*****************************************************/ 

{ 

DLGPROC lpfnDlg; 

if (lpfnDlg = (DLGPROC)MakeProcInstance( 

(FARPROC)FD1gProc, hins)) 

{ 

DialogBox(hins, MAKEINTRESOURCE(dlgSymEdit), 
NULL, lpfnDlg); 

FreeProcInstance((FARPROC) 1 pfnDl g); 
return TRUE; 

} 

return FALSE; 

) 


if (HIWORD(lParam) != BN_CLICKED) 
return FALSE; 

switch (wParam) 

( 

case didSystem: 

StopFontMix(); 
wParam = 0; 
break; 

case didSymbol: 

StopFontMix(); 

wParam = (WPARAM)hfntSym; 

break; 

case didMixed: 

FStartFontMix(hfntSym); 

wParam = 0; 

break; 

) /* End second switch wParam. */ 

SendDlgItemMessage(hwnd, didEdit, WM_SETFONT, 
wParam, TRUE); 

return TRUE; /* End case WM_COMMAND. */ 

) /* End switch wm. */ 

return FALSE; 

) 

/* End of File */ 


BOOL CALLBACK 

FD1gProc(HWND hwnd, UINT wm, WPARAM wParam, 

LPARAM IParam) 

^***************************************************** j 

/* — Dialog proc. */ 

j***************************************************** f 

{ 

static HFONT hfntSym; 

BYTE szBuf[257]; 

int ich; 

switch (wm) 

{ 

default: 

break; 

case WMJNITDIALOG: 

for (ich = 0; ich < 256; ich++) 
szBuf[ich] = (BYTE)(ich + 1); 
szBuf[256] = '\0*; 

SetDlgItemText(hwnd, didEdit, szBuf); 
if (!(hfntSym = CreateFont(0, 0, 0, 0, 
FW_DONTCARE, 0, 0, 0, SYMBOL_CHARSET, 
OUT_DEFAULT_PRECIS, CLIP_DEFAULT_PRECIS, 
DEFAULT_QUALITY, DEFAULT_PITCH | FF_DONTCARE, 
“Symbol"))) 

EndDialog(hwnd, FALSE); 
return TRUE; 

case WM_DESTROY: 
if (hfntSym) 

DeleteObject(hfntSym); 

StopFontMix(); 
break; 

case WM_COMMAND: 

if TwParam == IDOK || wParam == IDCANCEL) 



Rock-Solid Support 
For Software Development 


Btrv++ 

Exploit the power of object-oriented programming to achieve 
order-of-magnitude productivity gains over the use of Btrieve 
development tools alone! A dozen classes make developing single or 
multi-user LAN applications for DOS, Windows, and OS/2 a snap! 
Source for Btrv++ is included. Royalty free. And now you can get it for 
only $249. A savings of $100 off the regular price! 

Btrvgen++. $229 

Combine the power of object-oriented development with 
state-of-the-art code generation technology! Use Btrvgen++ to 
generate thousands of lines of C++ class library code - automatically! 
Inherent referential integrity checking, cascading deletes, relational 
joins, access to the schema through meta-tables. Import and export 
.DDF file format. Access your Btrieve tables from Xtrieve, Netware 
SQL, Access, any program that uses .DDF format! Requires Btrv++. 
Special bundle price: Btrv++ and Btrvgen++ for only $349. 

VBtrv $249 

Control And Function Libraries For Novell Btrieve 
Under Visual Basic For Windows Or MS-DOS! 

Visual Basic Developers: Discover how easy it can be to use Novell’s 
legendary Btrieve File Manager under Visual Basic For Windows! 
Our full-featured Toolbox controls and function-call library offer 
access to the full power of Btrieve v5.1, and a lot more! Btrieve 
development becomes a "point and click" activity with VBtrv! It’s 
never been easier! 

Includes complete documentation and sample programs. Royalty 
free. Function-call library also available for Visual Basic For 
MS-DOS! 

Classic Software, Incorporated 

1 3542 Pheasant Run Circle Ste. 8, Ann Arbor Ml 48108 

313-677-0732 (Voice/FAX) 


□ Request 143 on Reader Service Card □ 


May 1993 


Windows/DOS Developer’s Journal — Page 73 
























The encoding of a far jump is: 
OxEA OxXXXXXXXX 


Listing 8 symedith - Dialog IDs for SymEdit 

/*****************************************************/ 

/* symedit.h 

*/ 

/* -- Dialog ID'S 

for SymEdit. */ 

^*****************************************************j 

fdefine dlgSymEdit 

1000 

fdefine didEdit 

1001 

fdefine didStatic 

1002 

#define didSystem 

1003 

Idefine didSymbol 

1004 

Idefine didMixed 
/* End of File */ 

1005 


Listing 9 symedit.rc — Dialog resource for SymEdit 


j*****************************************************I 

/* symedit.rc */ 

/* — Dialog resource for SymEdit. */ 

J*****************************************************j 

ih'nclude <windows.h> 
linclude "symedit.h" 

dlgSymEdit DIALOG 6, 18, 254, 154 

STYLE DS_MODALFRAME | WS_P0PUP | WS_VISIBLE | 

WS_CAPTION | WS_SYSMENU 
CAPTION "Mixed Font Demo" 

FONT 8, "MS Sans Serif" 

BEGIN 


EDITTEXT 

didEdit, 2, 2, 192, 150, 

ES MULTILINE | WS VSCR0LL 

GROUPBOX 

“&Font:", -1, 1987 2, 54, 48 

CONTROL 

"&System", didSystem, "Button”, 

BS AUT0RADI0BUTT0N | WS GROUP, 

202, 14, 40, 10 

CONTROL 

"S&ymbol", didSymbol, "Button", 
BS_AUT0RADI0BUTT0N, 202, 38, 40, 10 

CONTROL 

"&Mixed", didMixed, “Button", 

BS AUT0RADI0BUTT0N, 202, 26, 40, 10 

PUSHBUTTON 

"&0K", ID0K, 198, 138, 54, 14, 


Listing 10 symedildef - Module definition file for 
font edit demo 


;; symedit.def 


j; -- Module 

definition file 

for font edit demo. ;; 

NAME 

SymEdit 


DESCRIPTION 

'Mixed Font Edit 

Demo' 

EXETYPE 

WINDOWS 


STUB 

'WINSTUB.EXE' 


CODE 

PRELOAD MOVEABLE 

DISCARDABLE 

DATA 

PRELOAD MOVEABLE 

MULTIPLE 

HEAPSIZE 

1024 


STACKSIZE 

10240 


EXPORTS 



FOlgProc 

@1 



where the OxXXXXXXXX is the far address of the code to 
jump to. With OxEA stored in bJump (the field preceding the 
address of my hook function in the structure), the five bytes 
in the structure starting at bJump form a valid jump instruc¬ 
tion, which jumps to my hook function. The HookHks() macro 
uses the address of bJump when it copies five bytes of data 
over the beginning of the function I want to hook. Then, the 
next time that function gets called, it executes those bytes, 
which form a jump instruction to my hook function. I keep 
the HKS structures for each of the routines to hook in the 
array rghks. This convenience lets me use a loop to install all 
the hooks at once (or restore all hooked routines at once), and 
is exploited by the SetAllHooksO macro. 

Managing Multiple Tasks 

A client application can enter mixed font mode by calling 
FStartFontMix (), a routine exported by SymDII. The DLL uses 
GetCurrentTaskf) to obtain the client's task handle and then 
adds it to the client list. Each entry in the client list has a slot 
for the task handle and a font handle for the second font. 
Different tasks can use different second fonts. The client list is 
implemented as an array of client data structures, Irgcds. F- 
StartFontMix() first looks for an empty slot in Irgcds and 
checks to make sure the task is not already present. If an 
empty slot is found, it is used, otherwise the array is grown. 
The count of clients is maintained in the variable ccdsClient. 
When the first client calls FStartFontMix(), this number is 
initially zero, which triggers the routine to install all the hooks 
and the NotifyRegisterf) callback. 

NotifyRegister() requires a task handle as one of its 
parameters, but since the DLL is installing only one callback on 
behalf of all its clients, it must keep track of which task hand¬ 
le the callback is registered with. Each time a client calls 
StopFontMix() to turn off mixed font support, the DLL must 
check to see if the task was the one passed to Not ify- 
Register() and uninstall the callback, since the client may be 
exiting. The variable htskReg maintains the current Notify- 
Register() task handle. StopFontMix() uses the utility func¬ 
tion LpcdsGetCurf) to determine if the calling task is a client. 
LpcdsGetCur() enumerates the entries in the Irgcds array, 
looking for the current task handle. If the current task is a 
client -and after removing the NotifyRegister() callback if 
it was installed with the current task —the DLL again traverses 
the client list, this time looking for another task to reinstall 
the callback with. Otherwise, if there are no other clients, it 
removes the hooks from the three functions by copying back 
their original code bytes. 

The DLL has two more support routines: its WEP (Windows 
Exit Procedure, which Windows automatically calls when un¬ 
loading the DLL) and the NotifyRegister() callback, FNotify- 
Proc(). The WEP ensures that all code segments have been 
restored (just in case a client aborted) and, if the current task 
did not call StopFontMix(), unregisters the NotifyRegister() 
callback. The WEP does not free the global memory occupied 
by Irgcds, even though it was allocated using GMEM_SHARE, 
since Windows will do this automatically when it unloads the 
DLL. 

Among the possible notifications, the NotifyRegister() 
callback, FNotifyProc(), pays attention to NFY LOADSEG and 
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NFY_EXITTASK. On a segment load 
notification, FNotifyProc() scans the 
HKS table and, if the selector portion of 
IpfnOrig matches the selector being 
loaded, calls the HookHks() macro to 
reinstall the jump. Since the callback is 
only installed when at least one client 
has called FStortFontMixf), FNotify- 
Proc() does not need to check the 
client count, ccdsClient. 

FNotifyProcf) uses the exit task 
notification to track clients that have 
exited without calling StopFontMix() 

(for example, because they aborted for 
some reason). LpcdsGetCur() checks to 
see if the current task, which is the one 
exiting, is a client. LpcdsGetCur() must 
call GetCurrentTask() (which is why 
the ability to call this routine from the 
callback is critical). If the exiting task is 
a client, StopFontMixf) is called to 
clean up. StopFontMixf) and the func¬ 
tions it calls rely only on Toolhelp func¬ 
tions and GetCurrentTaskf). 

The Hook Functions 

The remaining functions are the three hooks. They share 
some similar traits. Each is defined with exactly the same 
parameters as the function that it is going to hook (the 
“hookee"). This is necessary so that the right number of bytes 
get popped off the stack when the hook function returns, 
since it was not called directly. Each hook function has at least 
two calls to the hookee, one for each font. Each hook function 
starts by removing the jump instruction that was patched into 
the hookee. This allows the hook function to call the hookee 
without going into an infinite loop. Each hook function ends 
by patching the jump instruction back into the hookee. After 
removing the jump from the hookee, LpcdsGetCur() is called 
to see if the current task is a client (other programs will also 
be calling the hooked functions). If it is not, the hookee is 
called with unmodified parameters. 

The character mapping scheme implicit in the hooks is a 
simple one. The first 0x80 values (ASCII) are drawn in the 
original font. The characters from 0x80 to OxFF (high bit on) 
are drawn in the second font, after subtracting 0x80. The high 
bit determines the font, and mapping is achieved by dropping 
it. I chose this scheme to keep things simple, but you can 
easily implement any mapping you prefer by using a 256 two- 
byte table, indexed by original character value, to encode the 
mapped character and font. 

As already mentioned, HookGetTextMetrics() returns the 
maximum of the two font heights. It calls the hookee with the 
unmodified parameters to get the height of the first font, 
selects the other font into the device context, and makes the 
call again. The original font is then restored. HookGetChor- 
Uidth() fills in the width array, using the second font for 
character values over 0x80 and dropping the high bit first for 
these values. 


HookExtTextOut() is the most complicated of the three 
hook functions. It writes the input string in chunks of like font 
characters. To save keeping track of the new output position 
after writing each chunk of the string, I call the handy SetText- 
Aligr>() routine with TAJJPDATECP. This causes ExtTextOut() to 
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Listing 11 symeditmak - Project file for SymEdit 
and SymDII 


####################################################### 
## makefile.q2 ## 

## -- Project file for SymEdit and SymDII. ## 

####################################################### 
all: symedit.exe 

.c.obj: 

cl -c -ASw -G2w -Od -Zdipe -W3 -DSTRICT $(DEFS) $< 

symedit.obj: symedit.c symedit.h symdll.h 
symbase.obj: symbase.c symdll.h symhook.h symbase.h 
symhook.obj: symhook.c symdll.h symhook.h symbase.h 

symedit.exe: symedit.obj symedit.def symedit.rc \ 

symdll.dll 

link /NOD/MA symedit,,, libw slibcew symdll, \ 
symedit.def 
rc $(DEFS) symedit 

symdll.dll: symbase.obj symhook.obj symdll.def 

link /NOD/MA/CO symbase symhook libentry, \ 
symdll.dll,, libw sdllcew toolhelp, symdll.def 
implib symdll.lib symdll.def 
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ignore the starting coordinates I pass and instead start output 
at the “current position." After a chunk of text is output, the 
current position is updated to the position for the next chunk. 
MoveTof) is used to set the current position before entering 
the chunk output loop. 

You have to be careful with the fuOptions parameter. The 
edit control will use the ET0_0PAQUE flag, which directs Ext- 
TextOutf) to erase the rectangle specified by the Iprc 
parameter before writing the text. But since ExtTextOut() is 
being called once for each chunk, the background will keep 
getting re-erased, obliterating the previous chunks. After the 
first chunk is output, HookExtTextOut() turns the flag off if it 
was on, since the entire background will have been erased. 

When HookExtTextOut() writes a string in the second 
font, it strips the high bit of the substring just before calling 
the hookee. This means that the string must exist in a 
writable segment (for example, it cannot be a string constant 
that resides in a code segment). This restriction could be 
removed by allocating a buffer for a local copy of the string, 
but this introduces the complication of testing for not enough 
memory. The Windows edit control does not use code-based 
strings, so I chose the simple solution. 

Listings 7 through 10 implement a demo client application 
for SymDII (see Figure 1). The demo displays a dialog box con¬ 
taining a multiline edit control, a set of three radio buttons to 
select system, symbol, or mixed font, and an OK button. The 
dialog initially displays a 255-character string containing suc¬ 
cessive values 0x01 through OxFF (the null character is not 
displayable). The edit gets sent a new font with the UM_SET- 
FONT message each time you pick a radio button. When you 
pick the mix button, the font is set back to default, and F- 
StartFontMix() is called. Listing 11 is the makefile for both 
the DLL and demo application. 

Conclusion 

You can easily extend the DLL presented here to hook ar¬ 
bitrary Windows functions, not just those relating to text out¬ 
put. All that is necessary is to change the contents of the HKS 
array of Listing 4, provide the hook functions in Listing 3, and 
export them in the module definition file of Listing 6 (or use 
the _export keyword for the function definitions). You have to 
be careful of functions that can yield control to other tasks. As 
an example, if UaitMessagef) were hooked, the hook func¬ 
tion would remove the jump, call UaitMessage(), then 
reinstall the hook. The problem is that if another client had a 
message in its queue when UaitMessage() was called, it 
could be scheduled, and its call to UaitMessagef) would not 
have been hooked. 

While playing with the DLL, I noticed that calls to Memory- 
Uritef) were extremely slow, but I think this is because I am 
running the debug version of win386.exe supplied with the 
DDK. When running this version, each time MemoryUritef) is 
called, a message is written to the auxiliary port. I suspect 
that the time is being spent writing this message. Unfor¬ 
tunately, I don’t have a copy of the retail version of 
win386.exe handy, and am loath to reinstall Windows. Stand¬ 
ard mode does not exhibit the slowdown and does not use 
win386.exe, so I think my guess is justified. □ 
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Two Timer Tales and Other Goodies 


What t imercountf) Counts 


James K. Lawless 
1622 Avenue F 
Council Bluffs, IA 


I’d like to report a slight misprint in the Windows SDK help file regarding the 
TimerCount() Toolhelp function. The function is supposed to fill a TIMERINFO struc¬ 
ture with the elapsed time since the current task became active and the elapsed 
time since the current VM became active. If Windows is running in 386 enhanced 
mode, these values are supposed to be accurate to the millisecond, while standard¬ 
mode Windows uses the normal BIOS timer to get an approximation in milliseconds. 
I found that the dwmsSinceStart member of the TIMERINFO structure is not filled 
with the elapsed time since the task started, as the documentation states, but with 
the elapsed time since Windows started. If this function is used to time task dura¬ 
tions, you must first preserve the initial TIMERINFO. dmSinceStart and subtract a 
more current sample from it to determine the actual task duration. 

Listing 1 shows a set of code fragments that may be inserted into any window 
procedure to illustrate the behavior of the TimerCount() call. The initial message 
box will display the current value of TIMERINFO. dmSinceStart every time you 
press the OK button. Press the Cancel button to continue with the procedure. 
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Listing 1 TimerCount test fragments 


/* 

* Window Procedure fragments to test TimerCount documentation 

* bug in Windows API 

* Written by Leor Zolman, 2/93 
*/ 

/* Declarations at top of Window Procedure: */ 

TIMERINFO lpti; 
char timetext[100]; 

/* Code to be placed in WM_CREATE processing section: */ 
case WM_CREATE: 

Ipti.dwSize = sizeof (TIMERINFO); 

while (1) 

{ 

if (!TimerCount(&lpti)) 

MessageBox(hwnd, "Error running TimerCount!' 1 , 
"TimerCount Test 11 , MB_0K); 

sprintf(timetext, “SinceStart = %ld", lpti.dwmsSinceStart); 

if (MessageBox(hwnd, timetext, 

"TimerCount test", MB_OKCANCEL) == IDCANCEL) 
break; 

} 

/* ... */ 


Turbo getch 


Ronald R. Caudill 
6049 Clay City Dr. SE 
Uhrichsville, OH 44683 


Some C programming books give the 
following routine for a “pause and hit 
any key to continue” type of operation: 

printf(“Check printer for paper supply\n“); 
printfC'Hit any key to continue:\n"); 
getch(); 



This does implement “pause and con¬ 
tinue,” but if the user hits an extended 
code key (such as a cursor arrow or 
function key), then the second digit of 
the key code is left unsampled in the 
keyboard buffer. The next time the pro¬ 
gram reads the keyboard, that key will 
show up uninvited and cause confusion. 

Listing 2 shows an improved version 
of the same pause sequence, con¬ 
figured as a function named pause () 
that takes a message string as a 
parameter. This time, the code has the 
ability to absorb any “extra” characters 
of a multibyte sequence. 


Listing 2 tpause.c 

• 

/* 

void keyloop(void) 

* The pause() function, and test driver code 

i 

* Written by R. Caudill and L. Zolman, 3/93 
*/ 

int c; 

printf(“\nBeginning key loop. Press Ctrl-C to break out.\n“); 

linclude <stdio.h> 

while ({c = getch()) != 0x03) 

finclude <conio.h> 

printf(“Key received: \"%c\" (%02x hex)\n“, c, c); 
printf(“\nafter 1 oop.\n“ ) ; 

void pause(char *msg); 
void keyloop(void); 

1 

main() 

/* 

( 

* pause function 

printf("Test routine for pause() function.\n"); 

* Written by Ronald R. Caudill 

* Displays the supplied message, then waits 

printf("\nAbout to do a simple getch () call. " 

* for the user to press a key. Multi-byte key codes 

"Try a Function key: "); 

* are properly cleared from the keyboard input buffer. 

getch(); 

* 

printf(“\n“); 


keyloopf); 

void pause(char *msg) 

pause("This is the message to be printed by pause()"); 

puts(msg); 

keyloop(); 

printf ("Hit any key to continued"); 


if (!getch()) 

return 0; 

\ 

getch (); 

} 

/* 

* Read and echo keystrokes and their hex ASCII values 

/* End of File */ 

*/ 
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Listing 3 wheiio.c 


/* 

return FALSE; /* Stop enumerating */ 

* wheiio.c 

1 

* Basic Windows app, to illustrate usage of find prev win() function 

return TRUE; /* Continue enumerating */ 

* (adapted by LZ from hellowin.c in Petzold's Programming Windows 3.1) 

} /* find_prev_wnd() */ 


/******** END OF CUSTOM SECTION #1 ********/ 

#include <windows.h> 


long FAR PASCAL _export WndProc (HWND, UINT, UINT, LONG); 

int PASCAL WinMain (HANDLE hlnstance, HANDLE hPrevInstance, 

LPSTR IpszCmdParam, int nCmdShow) 

1 

/******** BEGINNING OF CUSTOM SECTION #1 ********/ 

1 

static char *appid - "HelloWin w/Return”; 

! ******************************************************************* 

HWND hwnd; 

MSG msg; 

* find prev wnd() : * 

WNDCLASS wnddass; 

* Find the main window of the previous * 


* instance by searching all top-level windows * 

/***** BEGINNING OF CUSTOM SECTION #2 *****/ 

******************************************************************** i 


HWND prev wnd; 

! **************************************************************** 

* If there is a previous task instance, return to it * 

**************************************************************** j 

WNDENUMPR0C find prev wndi; 



if (hPrevInstance) 

BOOL CALLBACK export find prev wnd(HWND this wnd, LPARAM hPrevInst) 

( 

1 

find prev wndi * 

/* Look for a true top-level window having the same instance */ 

IWNDENUMPROC)MakeProcInstance((FARPROC)find prev wnd. 

if (!GetParent(this wnd) && 

hlnstance); 

GetWindowWord(this wnd, GWW HINSTANCE) “ LOWORD(hPrevInst)) 

EnumWindows(find prev wndi, (LPARAM)hPrevInstance); 

{ 

FreeProcInstanceI(FARPROC)find prev wndi); 

prev_wnd = this_wnd; 



Th emain() and keyloopO functions 
serve to illustrate the behavior dif¬ 
ference between a simple getch() call 
and the use of the pause () function. 


The first time the program stops to read 
a key, try pressing a function key or a 
cursor-movement key. The program will 
continue into the keyloopO call, and 


the second key of the sequence will 
then be reported. Press Ctrl-C to exit 

(text continued on page 82) 
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maximum reuse of code by applying encapsulation, 
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□ 


tation at your location, for a minimum of 5 students. Our list of 
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Listing 3 continued 


/* Error: Prev instance has no window */ 
if (!prev_wnd) 

return 0; /* Fail silently */ 

/* Return to the last active popup window, if any, 
of the previous instance */ 
prev_wnd * GetLastActivePopup(prev_wnd); 

/* If the existing window is minimized, restore it */ 
if (IsIconic(prev_wnd)) 

ShowWindow(prev_wnd, SW_REST0RE); 
SetActiveWindow(prev_wnd); 
return 0; 

) /* There is a previous instance */ 

/******** END OF CUSTOM SECTION #2 +*+*****/ 


wndclass.style 
wndclass.1pfnWndProc 
wndclass.cbClsExtra 
wndclass.cbUndExtra 
wndclass.hlnstance 
wndclass.hlcon 
wndclass.hCursor 
wndclass.hbrBackground 
wndclass.1pszMenuName 
wndclass.1pszClassName 


= CS_HREDRAW | CS_VREDRAW; 

= WndProc; 

- 0; 

= 0 ; 

• hlnstance; 

- Loadlcon (NULL, IDI APPLICATION); 

■ LoadCursor (NULL, IOC ARROW); 

= GetStockObject (WHITE~BRU'H); 

= NULL; 

■ appid; 


RegisterClass (Awndclass); 

hwnd * CreateWindow (appid, // window class name 

“Hello w/Return”, // window caption 
WS 0VERLAPPEDWIN00W I WS_VISIBLE, // window style 
0 , 0 , 200 , 200 , 

NULL, // parent window handle 

NULL, // window menu handle 

hlnstance, // program instance handle 

NULL); // creation parameters 

ShowWindow (hwnd, nCmdShow); 

UpdateWindow (hwnd); 


while (GetMessage (&msg, NULL, 0, 0)) 

( 

TranslateMessage (&msg); 
DispatchMessage (&msg); 

1 

return msg.wParam; 


long FAR PASCAL export WndProc (HWND hwnd, UINT message, 

UINT wParam, LONG IParam) 

( 

HOC hdc; 

PAINTSTRUCT ps; 

RECT rect; 

switch (message) 

( 

case WM_PAINT: 

hdc * BeginPaint (hwnd, &ps) ; 

GetClientRect (hwnd, &rect) ; 

DrawText (hdc, "Hello, Windows! 11 , -1, &rect, 

DTJINGLELINE | DT_CENTER | DT_VCENTER) ; 
EndPaint (hwnd, &ps) ; 
return 0 ; 


case WM_DESTROY: 

PostQuitMessage (0); 
return 0; 

) 

return DefWindowProc (hwnd, message, wParam, IParam); 

) 

/* End of File */ 


Listing 4 

whello.def 

; whello.def Module Definition 

NAME 

whello 

DESCRIPTION 

'Basic hello app, with auto-detection of multiple \ 
instances' 

EXETYPE 

WINDOWS 

STUB 

■WINSTUB.EXE* 

CODE 

PRELOAD MOVEABLE DISCARDABLE 

DATA 

PRELOAD MOVEABLE MULTIPLE 

HEAPSIZE 

1024 

STACKSIZE 

16384 


Listing 5 whello.mak 


# Borland C++ 3.1 Makefile for whello app: 

whello.exe : whello.obj whello.def 

tlink /c/n /Tw cOws whello, whello, NUL, import mathws cws, \ 
whello 

rc -t whello.exe 

whello.obj : whello.c 
$(WINCC) whello.c 


Listing 6 timer.c 


/* 

* Timer function library 

* Compile (Borland C++): 

* bcc -c timer.c 
*/ 

^include <dos.h> 
finclude "timer.h" 
fpragma inline 

fdefine TimerResolution 1193L 


unsigned long cardinal(long 1) 

( 

if (1 < 0L) 

return(((unsigned long)~0 + (long)1) + 1); 
return ((long)1); 

} 

unsigned long elapsedtimeflong start, long stop) 

( 

return((unsigned long)(cardinal(stop - start) / TimerResolution)); 

I 

void initializetimer(void) 

( 

outp(0x043,0x034); 
asm\ 

T 

jmp short NullJumpl 

) 

NullJumpl:; 

outp(0x040,0x000); 
asm\ 

I 

jmp short NullJump2 

) 

NullJump2:; 
outp(0x040,0x000); 
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Listing 6 continued 




in al,040h 

/* Counter --> bx*/ 

void 

mov bl.al 

/* LSB in BL */ 

restoretimer(void) 

in al,040h 


( 

mov bh,al 

/* MSB in BH */ 

outp(0x043,0x036); 

not bx 

/* Need ascending counter */ 

asm\ 

in al,021h 

/* Read PIC imr */ 

( 

mov si,ax 

/* Save it in SI */ 

jmp short NullJumpl 

mov al.OOFFh 

/* Mask all interrupts */ 

) 

out 021h,al 



mov ax,040h 

/* read low word of time */ 

NullJumpl:; 

mov es,ax 

/* from BIOS data area */ 

outp(0x040,0x000); 

mov dx.es:[06Ch] 


asm\ 

mov ax,si 

/* Restore imr from SI */ 

I 

out 021h,al 


jmp short NullJump2 

sti 

/* Enable interrupts */ 

) 

mov ax.di 

/* Retrieve old irr */ 


test al,001h 

/* Counter hit 0? */ 

NullJump2:; 

jz done 

/* Jump if not */ 

outp(0x040,0x000); 

cmp bx.OFFh 

/* Counter > OxOFF? */ 


ja done 

/* Done if so */ 

i 

inc dx 

/* Else count int req. */ 

Ipragma warn -rvl /* shut up Turbo C warning about return value */ 

done: 


long 

asm\ 


readtimer(void) 

{ 


{ 

mov ax,bx 

/* set function result */ 

asm\ 

} 


T 

i 


cli /* Disable interrupts */ 
mov dx,020h /* Address PIC ocw3 */ 
mov al.OOAh /* Ask to read irr */ 

#pragma warn .rvl 

/* reset Turbo C return value warning */ 

out dx.al 

unsigned long msleep (long pause) 

mov al.OOh /* Latch timer 0 */ 

i 


out 043h,al 

long start, stop; 

in al,dx /* Read irr */ 

mov di.ax /* Save it in DI */ 

unsigned long time; 
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(continued from page 79) 

keyloopO, and the program will set up for a call to pausef). 
When in the pause () call, try the function or cursor arrow key 
once more; this time, in the subsequent keyloopO call, there 
will be no leftover characters reported in the keyboard buffer. 



Returning to Previous Instances of Windows Apps 


David Spector 
Springtime Software 
81 Amherst Ave. 
Waltham, MA 02154 


Just about the most common programming task required 
for each application I write for Windows is located at the 
beginning of UinMainf), namely code to ensure that at most 
one instance of the application can exist. All this code has to 

Listing 6 continued 


initializetimer (); 
start = readtimer(); 
time = 0.0; 

while (elapsedtime (start, stop = readtimer(J) < pause) 
restoretimer(); 

time * elapsedtime (start, stop); 
return (time); 

} 

/* End of File */ 


do is return to the previous instance, if any. Sounds simple, 
right? Well, there's no Windows function to do itl Not only 
that, but the existing published examples I've seen fail in a 
number of simple situations. 

Listing 3 illustrates the use of some generalized code that 
you can plug right into your applications to accomplish this 
common task. The application is an adaptation of the "hel- 
lowin” application from Charles Petzold's excellent windows 
programming tutorial book, Programming Windows 3.1. Listing 
4 shows the .def file, and Listing 5 shows the makefile. 

The added sections of code (in Listing 3) are delimited by 
CUSTOM SECTION #1 and CUSTOM SECTION #2 comments. The 
code is ANSI C and has been tested under Turbo C for Win¬ 
dows and Borland C++ 3.1. Some compilers (including TCW) do 
not require the use of procedure instances (using the Make- 
ProcInstance() and FreeProcInstanceO calls). 

A Millisecond-Resolution Timing Library 

Fred C. Smith 
20 Whipple St. 
Stoneham, MA 02180 
617-438-5471 (home) 
fcshomelfredex@merk.com 


I've spent some time working with a public-domain pack¬ 
age of timer routines (as described below), making enough 
changes to justify a new release. 

I have modified the elapsedtime() function (in timer.c, 
the main timer library, shown in Listing 6) so that it now 



Listing 7 beep.c 

/* 

if (freq > 0 66 freq < 19) 

* beep.c 

freq =19; /* smallest number where result fits 

* This routine causes the system speaker to emit a beep 

an unsigned int +/ 

* of the specified pitch and duration. 

if (freq != 0) 

* 

( /* compute the proper count */ 

* Writen 2/92 by Fred C. Smith 

count.divisor*(unsigned int)(1193280L/freq); 

* 

outportb (67, 182); /* tell 8253 that count 

* (Heavily modified from code found in one of the books of 

is comming */ 

* Herbert Schildt--Sorry, 1 forget which one!) 

outportb (66, count.cfO]); /* send low-order byte */ 

* 

outportb (66, count.c[l]); /* send high-order byte */ 

* Compile (Borland C++): 

p = inportb (97); /* get existing bit pattern */ 

* bcc beep.c timer.obj 
*/ 

outportb (97, p j 3); /+ turn on bits 0 and 1 */ 

) 

♦include <stdio.h> 

/* start counting 4 continue til enough time has passed */ 

♦include <stdlib.h> 

pause = duration; 

♦include <dos.h> 

start = readtimer (); 

linclude <conio.h> 

while (elapsedtime (start, readtimer ()) < pause) 

linclude "timer.h M 

: 

/* Beep the speaker using the specified frequency. */ 

if (freq != 0) 


outportb (97, p); /* restore orig. bits to turn off 

void beep (int freq, long duration) 

speaker */ 

/* int freq; in Hertz ?? */ 

) 

/* long duration; in milliseconds */ 


1 

main (int argc, char ** argv) 

unsigned i; 

1 

union 

initializetimer (); 

i 

if (argc != 3) 

unsigned short divisor; 

exit(fprintf(stderr, "usage: %s freq duration\n", argv[0] )) ; 

unsigned char c[2]; 

beep (atoi (argv[1] ) , (long) atoi (argv[2])J; 

) count; 

restoretimer (); 

unsigned long pause, start; 

return 0; 

unsigned char p; 

} 


/* End of File */ 
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returns an unsigned long representing 
the number of milliseconds elapsed 
since start and stop. The original version 
(described below by Dean Pentcheff) 
returned a double representing the 
elapsed time in seconds. This worked 
just fine, but I didn't want to pay the 
price (in bloat) of having to load float¬ 
ing-point code into the program just to 
get this feature. 

All the function prototypes shown 
below have been updated to reflect this 
change. 

This stuff, as it stands now, compiles 
and runs just fine when compiled with 
Microsoft QuickC 2.0. I assume that it 
will also work with later versions of 
QuickC and with MSC 6.0 — but not MSC 
5.1, as it lacks the in-line assembler 
support. 1 have not updated the 
makefiles for Microsoft C. It’s not a big 
deal to compile, though. For QC2.0 just 
do: 

qcl -c timer.c 

and you will get timer.obj, for in¬ 
clusion in other programs. 

[Note: I have compiled and tested 
all code under Borland C++ 3.1, with 
no changes required other than the addition of a few 
prototypes to keep the compiler happy. The listings contain 
these added prototypes. -Iz] 

I have added a few demo programs to the package as I 
originally found it: 

beep.c (Listing 7) provides a C-callable function, beep(), for 
producing various sounds from the speaker. Parameters are 
frequency and duration (in milliseconds). The file beep.h con¬ 
sists of some C preprocessor macros that are useful in applica¬ 
tion programs (in conjunction with beep.c) for producing 
various types of sounds from the speaker. I've included a 
main() function in beep.c to drive beep() as a DOS command 
taking command-line arguments for the tone frequency and 
duration. 

sleep.c (Listing 8) simply goes to sleep for the specified 
number of milliseconds. It may not be terribly robust, but it 
works. 

Before using the timer functions, it is necessary to call in- 
itializetimer() ; when finished, the program must call res- 
toretimer(). If the timer is not initialized, the timing functions 
will appear to work, but the results will be wildly erratic (this 
is based on personal experience). If the timer is not restored 
when done, “bad things" may ensue (although I haven’t had 
the personal pleasure of finding out what these bad things 
might be). 



/* sleep.c 
* 

* A sample program that goes to sleep for the number of milliseconds 

* given in its first parameter. 

* 

* Not terribly robust, as it can be terminated by a *C or ~BREAK. 

* It ought to trap those events and exit cleanly, but it doesn't. 

* 

* Compile (Borland C++): 

* bcc sleep.c timer.obj 
*/ 

♦include <stdio.h> 

♦include <stdlib.h> 

♦include "timer.h“ 

unsigned long msleep (long); 

main (int argc, char ** argv) 

( 

long pause; 
unsigned long time; 

if (argc < 2) 

{ 

fprintf (stderr, “Usage: msleep <time in milliseconds>\n“); 
exit (0); 


pause = atol (argv[1]); 
time = msleep (pause); 
printf ("%ld\n“, time); 
return 0; 


/* End of File */ 


To claim the territory, 
have a trustworthy guide. 



(Rapture international markets by making your 
software easy to localize! Let InternaX videotapes, 
with Windows and Windows NT expert Dr. William 
Hall, show you how to design or retrofit your soft¬ 
ware for global success! 

For details, phone or fax 

( 408 ) 438-2270 

InternaX 

6 Johnston Way, Scotts Valley, CA 95066 

Windows™ is a registered trademark of Microsoft Corporation 


□ Request 101 on Reader Sen/ice Card □ 


May 1993 


Windows/DOS Developer’s Journal — Page 83 








Listing 9 ttesttime.c 

/* 

start time, stop time); 

* Test routine for the timer functions 

time = elapsedtime(start time, stop time); 

* Compile (Borland C++): 

printf("time of a 'msleep(571) 1 call : %6.3f s (%ld ms)\n". 

* bcc testtime.c timer.obj 
*/ 

time/1000., time); 

♦include <stdio.h> 

printf( M \n\nPress any key to start the timer..An"); 

linclude <dos.h> 

if (IgetchO) 

linclude <conio.h> 

getch(); 

♦include “timer.h“ 

start_time=readtimer(); 

void main() 

printf(”\nTiming until you press a key..."); 

< 

if (IgetchO) 

long start time; 

getch(); 

long stop time; 

stop time = readtimerQ; 

unsigned long time; 

time = elapsedtime(start time, stop time); 

long i,j; 

printf( M \b\b\b\b\b\b\b\b\bed a key: %6.3f s (%ld ms)\n". 

initializetimer(); 

time/1000., time); 

start time ■ readtimer(); 

restoretimer(); 

msleep(571); 

i 

stop time=readtimer(); 

/* End of File */ 

printf ("start_time = %ld, stop_time = %ld\n“. 



For reference purposes, I include here a portion of Dean 
PentchefFs documentation for the original public domain 
release: 


Source Code Availability 

Bulletin Board Si 

/stems 

Phoenix Chapter 
ACM Library 

(602) 970-0474 

The 

Programmer’s 

Corner 

(301) 596-7692 or (410) 995-6873 

The Courts of 

Chaos 

(501) 985-0059 

EmmaSoft 
Shareware Board 

(607) 533-7072 

Cornerstone 

(206) 362-4283 

Other Systems 

CompuServe 

GO CLMFORUM, section 7 

BIX/WIX 

join listings, change areas to 
“win.dos.dev" 

uunet 

“/published/windowsdos/19YY/monYY.zip 
Accessible via anonymous FTP from 
ftp.uu.net or via uucp from 
(900) GOT-SRCS (login name “uccp", no 
password, $.50 per minute). 

Code disks for each issue can also be ordered from R&D 
Publications, Inc. at (913) 841-1631. 


Dean Pentcheff 

Department of Integrative Biology 

University of California at Berkeley 

dean@violeLberkeley.edu 

The code presented here [Listing 6] provides PC programs 
with a millisecond resolution timer. It is entirely based on 
“tctimer" 1.0 by Bichard S. Sadowsky (released to the public 
domain 8/10/88) which, in turn, is based on "tptime’ by Brian 
Foley and Kim Kokkonen of TurboPower Software (also public 
domain). 

These routines reprogram the timer chip, so they probably 
won’t work if your program does the same. Other than that, 
there should be no incompatibility problems. They do not inter¬ 
fere with Turbo's sound () and nosound () functions. 

I've tested these under Turbo C 2.0. Note that the file 
timer.c must be separately compiled with the standalone tcc 
compiler since it uses in-line assembly. Attempting to compile 
it under tc will result in compile-time error messages. 

The routine initializetimer() must be called first to 
reset the timer. The calling program must also call res- 
toretimer() before exiting to reset the timer to its original 
state. 

[The routines included are shown in Table 1 — see 
tes ttime.c, Listing 9, for examples.] 

Limitations 

Because long integers are used to represent time, tctimer 
cannot be used to time events longer than about 60 minutes 
[given that 4,294,967,295 equals $FFFFFFFF, the largest unsigned 
value represented by long int, and 1,193,181 is the timer 
resolution in counts/second: (4,294,967,295 / 1,193,181) / 60 = 
59.9]. 

This should hardly be a problem, however, since an event 
longer than an hour presumably doesn’t need to be timed with 
1-millisecond accuracy anyway. 

Also note that the process of reading the time takes time. 
Hence, results of timing very short events will be skewed by 
the overhead of reading the timer. Table 2 shows the time 
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measured between two calls to Read- 
Timer (), one right after the other. 

Hardware compatibility note: Timing 
problems have been observed when 
running this timer code on some fast 
486 processors. I am guessing this is 
because the 486, with its fast internal 
cache, causes commands to be sent 
to the timer chip too rapidly in succes¬ 
sion. If any reader comes up with a fix 
for this problem that can be plugged 
into the timer code, I’d be glad to 
publish it. -Iz □ 


Table 1 Routines included in timer.c 

Function 

Description 

void initializetimer(void) 

Reprogram the timer chip to allow 1 
millisecond resolution. 

long readtimer(void) 

Read the timer with 1 millisecond resolution. 

unsigned long 

elapsedtime(long start, long stop) 

Calculate time elapsed (in 
milliseconds)between Start and Stop. 

void restoretimer(void) 

Restore the timer chip to its normal state. 


Table 2 Time measured between two calls to Readtimer 

Machine 

Time 

Function 

Toshiba 1000 (4.77MHz 8088) 

125 microseconds 

tctimer 

ATT 6300 (8MHz 8086) 

53 microseconds 

tctimer 

Deskpro 286 (8MHz 80286) 

35 microseconds 

tctimer 

Sperry IT (7.1MHz 286, 0 wait) 

32 microseconds 

tctimer 

IBM PS/2 model 50 

25 microseconds 

tctimer 

PC Designs GV386 (16MHz) 

27 microseconds 

tctimer 

PC Source Standard 286 (10MHz) 

21 microseconds 

these routines 
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Updated! 

Updated! 

Updated! 

NEW! 

NEW! 


NEW! 


NEW! 

NEW! 


C CODE FOR THE PC 

source code, of course 

Embedded DOS (full-features, real-time, multitasking, 3.31-compatible DOS for embedded system and self-bootable installations).$375 

Code Base 4 (database manager, dBase and Clipper compatibile indexes & data files; Version 5.0; specify C or C++) ..$325 

ZIP Image Processor & Victor Image Library Version 2.2 (brightness, contrast, merge images, TIFF/GIF/PCX/bin, HP ScanJet support) . . $290 

The Snooper (Ethernet protocol analyzer for Novell Netmre and LAN Manager Networks; capture packets; real-time display).$275 

TirboTteX (Release 3.0; HP, PS, dot drivers; CM fonts; LaTfcX; MetaFont)..$250 

Rogue wave tools.h++ or math.h++ Class Library (extensive docs).each $240 

C Communications Tbolkit by Magna Carta (Version 2.0; multi-port & co-processor support, FAX, interrupt driven, emulations, xfer protocols) $210 

PxSQL (SQL for Borland's Paradox Engine; ANSI X3.135-1969 SQL-DML standard; network server not required).$180 

cjaslib (PostScript generation library for C programs; includes complete graphics, font, rotation & paragraph support).$170 

Viewpoint (C+ + graphics library; 312-bit color, pattern fill, scroll & bitmap, coordinate tranformations).$170 

TE Editor Developers Kit Ver. 3.0 (full screen editor, undo command, multiple windows; with Word Processing $230).$155 

Minix Operating System (Version 1.5; Unix-like operating system, includes manual; specify 5.25” or 3.5” diskettes).$150 

ViewTHeve (relational view of Novell Btrieve databases; includes EZTHeve).$150 

Delorie GCC for MS-DOS (Version 222; includes C++, assembler, DOS extender, 387 emulation; complete source code and makefiles) . . $150 

Booter Tbolkit (floppy disk bootstrap routines, DOS file system, light-weight multitasking, windows, fast memory management) .$120 

Ibrow (Version 4.0, programmer’s Windows-based editor; large files, help, undo/redo, drag-n-drop, function & type tags).$115 

Dr. MD (runtime memory analyzer & debugger, find many memory corruption errors; examine memory usage).$110 

386BSD Version 0.1 & LINUXVersion 0.96(two Unix clones for Intel 386).$100 

PC7IP (CMU/MIT TCP/IP for PCs; Ciynwr drivers, NFS server, Bdale mailer, PCRoute/PCBridge, ND1S/ODI drivers, Beholder, more) . . . $100 

Demacs (complete GNU Emacs for DOS; needs djgcc to build; based on 18.55).$100 

S cript Interpreter (a command script interpreter for DOS-based systems; C-like script language; lots of features).$90 

NETS Version 3.0 (neural net simulator from COSMIC) .$85 

Ibrow (programmer’s Windows-based editor; large files, help, undo/redo, drag-n-drop, function & type tags).$115 

HorC+ + raver (C+ + Class Library for Borland’s Paradox Engine)..$80 

ET Neural Net (back error propagation; specify DOS or Windows).$75 

FlexList (doubly-linked lists of arbitrary data with multiple access methods; specify Cor C++).$65 

LDB (Loose Data Binder; persistent data objects for C++; handles pointers between objects) .$60 

Kier DateLib (all kinds of date manipulation; translation, validation, formatting, & arithmetic).$60 

Coder’s Prolog (Version 3.0; inference engine for use with C programs).$60 

PCCTS (Purdue Compiler Construction Tbol Set; ported to Microsoft Q like YACC and LEX together with lots of additional features) . . . $60 

MEM.WING (global memory manager for Windows, supports standard C memory allocation calk to "wing” your old C code into Windows) , $55 

BigFloat (arbitraiy precision floating point arithmetic and functions; includes BCD conversion).$50 

EZCalc (ASCII algebraic expression evaluator, unlimited parenthesis nesting, symbols, 32 built-in functions, easily extended).$50 

Backup & Restore Utility by Blake McBride (multiple volumes, file compression & encryption).$50 

SuperGrep (exceptionally fast, revolutionary text searching algorithm; also searches sub-directories).$50 

Moby Crypto (encryption/decryption routines; Vol.l: DES, Lucifer, SRNG, ARNG; Vol. 2 PGP, RSA, MD4, SHA; both vols. $75) . . . each $50 

OBJASM (convert .obj files to .asm files; output is MASM compatible) .$50 

CLIPS Version 5.1 (rule-based expert system generator, advanced manuals available at additional cost).$50 

NIH Class Library & Book (basic C-(—h classes & Data Abstraction and Object-Oriented Proffammingm C+ + in softback by Keith Gorlen) $50 

Editor Pack (20 public domain editors; microEmacs 3.11, Stevie, Elvis, Moke, mg2a, DTE, Jove, Origami, CE & GRIEF).$50 

MicroC C Compiler (retargetable C compiler/optimizer, lots of docs, very portable, 8086 tables included; tables for 7 extra epu’s $50) .... $50 

PICTOR (Video library; multi-pane windows, menus, hypertext help, serial communications; text editor example; much more).$45 

TOUR (beautiful traveling salesman problem solver, finds minimum length paths quickly, includes graphics & plotting programs) .$40 

DES Enayption & Decryption (2500 bits/second on 4.77 MHz PC for on-the-fly encryption at 2400 baud; domestic distribution only) .... $40 

Database Pack (9 databases - simple to complex: isam, bplus, AVL, SDB, ID, gdbm, Requiem, Ingres89, Postgres).$35 

COP (poor man’s C++; C macro package which implements C++in C) .$35 

RXC & EGREP Version 20 (Regular Expression Compiler and Pattern Matching; finite state machine from regular expression).$35 

Database Pack (9 databases - simple to complex: isam, bplus, AVL, SDB, ID, gdbm, Requiem, Ingres89, Postgres).$35 

Bison & BYACC (YACC workalike parser generators; documentation; includes C and C+ + grammars) .$35 

Spell Pack (6 spelling programs, a hyphenator, 2 utility packs and a 60K word list: Ispell, Microsp, Sp, Cspella, Spell, Dawg, Soundex) .... $30 

Alloc-GC (a garbage-collecting memory allocation library).$30 

REGX Plus (Version 20, search and replace string manipulation routines based on regular expressions).$30 

GNU Awk & Diff for PC (both programs in one package).$30 

Big Number Pack (7 arbitrary precision arithmetic packages in C, one in Fortran but free Fortran-to-C converter is included) .$30 

Crunch Pack (30 file compression & expansion programs; now includes portable ZIP).$30 

UUPC Pack (UUCP for the PQ UUPC Version 1.11V, smail & snews) .$25 

PERL for MS-DOS (Version 4.019; C, sed, awk, and shell all rolled into one language; indudes hardcopy docs).$25 

FLEX (fast lexical analyzer generator; new, improved LEX; BSD Version 23.6 with docs’).$25 

GNU RCS (FSFs version of the Revision Control System; like Unix’s SCCS only better; keeps track of software development).$20 

PCAL Personal Calendar (generates PostScript calendar for any month or year, lots of options, personalization file for your dates & schedule) $20 

Publisher’s Interchange Language (PIL Tbol Kit, Version 5.0, API 20 by Quark).$20 

NetCDF (Network Common Data Form; general-purpose data exchange for scientific data; many tools and programs available).$20 

Simple Socket Library (Unix, VMS and MS-DOS; sits on TCP/IP stack).$20 

Bywater BASIC Version 1.10 (complete BASIC interpreter and interactive programming environment).$20 

Data 

Moby Thesaurus (25K root words, 1.2M synonyms).$350 

Moby Part-of-Speech (200,000 words and phrases described by prioritized part(s)-of-speech).$120 

Moby Words (500,000 words & phrases, 9,000 stars, 15,000 names).$80 

Moty Shakespeare (plays, sonnets, etc. ... every last word).$60 

Dictionary Word List (234,932 words in alphabetical order).$60 

Roget’s 1911 Thesaurus .$40 

U. S. Cities (names & longitude/latitude of 32,000 U.S. cities and 6,000 state boundary points).$35 

CIA World Bank II Database (13MB of maps, 5.7M vectors; coastlines, rivers, political boundaries; Africa, Asia, Europe, N. & S. America) $35 

The World Digitized (100,000 longitude/latitude of world country boundaries).$30 

Lots ’O Words (160,086 German, 178,430 Dutch, 61,843 Norwegian, 60,453 Italian, 138,257 French, 53,142 English).$30 

Tfext Pack (1990 CIA World Fact Book, Hacker’s Jargon FUe, Acronyma, Koran, Mormon Scriptures, One Liners, Mnemonics, more) .... $25 

CD-ROMs 

FontMaster Library (soft fonts for HP and HP compatible laser printers, 36 different type faces; 5,200 bit mapped fonts; 300MB).$70 

Prime Time Freeware (over 1 gigabyte of Unix C code).$60 

Walnut Creek Libris Britannica (over 600MB of the best of British boards; not all source included).$55 

Linux/GNU/X by Yggdrasil Computing (beta release; run from the CD; TCP/IP & NFS; drivers; MPEG; SCSI support; lots more).$60 

Walnut Creek CUsePs Group (Volumes 100 to 364).$40 

Whlnut Creek XUR5 and GNU (X11R5 with contributed and compsourcesjt, over 120 GNU programs, complete C source).$35 

Whlnut Creek Usenet and Simtei Unix-C (600MB).$35 

Walnut Creek Simtei 20 MSDOS Archive (C source code but lots of other stuff too).$20 

Sprite Network Operating System (source code & documentation of Ousterhout’s Sprite O/S; Sun and DECStation boot images).$20 

The Austin Code Works Voice: (512) 258-0785 

11100 Leafwood Lane much more ... ask for catalog FAX: (512) 258-1342 

Austin, Texas 78750-3587 USA E-mail: info@acw.com 
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New Products 

Industry-Related News & Announcements 


GUI Version ofMEWEL Ships 

MEWEL is an implementation of the Windows API that 
runs under DOS, OS/2, and UNIX. Vendors can take their 
original Windows C or C++ program and recompile and relink 
with the appropriate MEWEL library to produce an applica¬ 
tion that runs under DOS, OS/2, or UNIX. The MEWEL/GUl User 
Interface Library now extends the MEWEL family to graphics¬ 
mode DOS applications, to handle bitmaps, icons, fonts, and 
all the graphical elements of a Windows program. The com¬ 


pany has also extended Borland's ObjectWindows (OWL) and 
Microsoft's Foundation Class (MFC) frameworks so that they 
can produce either DOS graphics or DOS text-mode applica¬ 
tions using MEWEL. 

MEWEL/GUl costs $395, or $695 with source. For more in¬ 
formation, contact Magma Software Systems, 15 Bodwell 
Terrace, Millburn, NJ 07041, (201) 912-0192. 


Blue Sky Matches Visual C++ Release 

WindowsMAKER Professional is a prototyping and code 
generation tool for quickly developing and maintaining Win¬ 
dows user interfaces. Blue Sky Software has released version 
5.0 of the product, which includes compatibility with 
Microsoft’s new Visual C++. WindowsMAKER Professional in¬ 
tegrates with the Visual Workbench in Visual C++ and 
replaces the AppWizard and ClassWizard. 

With WindowsMAKER Professional, you can add 
functionality at any time. WindowsMaker Professional also 
maintains MFC message maps for you as ClassWizard does, 


but without any need to delimit parts of the code with spe¬ 
cial comments. You can also purchase different code genera¬ 
tion modules to generate code for Windows NT or Win32s, 
ANSI C, OWL, OS/2, XVT, and others. 

WindowsMAKER Professional v5.0 costs $995, including 
the code generation module for Microsoft's Foundation Clas¬ 
ses (MFC). For more information, contact Blue Sky Software 
Corporation, 7486 La Jolla Blvd., Suite 3, La Jolla, CA 92037, 
(619) 459-6365 or (800) 677- 4946; FAX (619) 459-6366; 

CIS 71052,1641. 


DataDraw Provides Data Structure Generation 


DataDraw lets Windows and DOS developers using C or 
C++ graphically design data structures by drawing schemas. 
The DataDraw schema editor runs under Microsoft Windows 
3.0 and lets you define objects, along with their properties 
and relationships. Once you complete the design, the 
schema editor can automatically create the C files that 
define and support all the objects and their methods. You 
can also use the tool to create methods for building and 


traversing relationships, and for saving and loading the bi¬ 
nary objects to disk. 

DataDraw costs $179, comes with a 30-day, money-back 
guarantee, and can be ordered from Programmer's Paradise 
at (800) 445-7899. The product includes all the code genera¬ 
tion source code so that you can customize its output For 
more information, contact DataDraw, 1613 Butano Dr., Mil¬ 
pitas, CA 95035, BBS (408) 956-0576. 


CV/lCEing Enables Hardware-assisted Debugging 


The 80386 and 80486 offer powerful hardware debug¬ 
ging support, such as trapping accesses to particular 
memory locations. Unlike Borland’s Turbo Debugger, 
Microsoft’s CodeView provides little access to these ad¬ 
vanced features. CV/ICEing for DOS is a new product that at¬ 
taches itself to CodeView to let you set breakpoints on 
debug registers, interrupts, I/O ports, and memory ranges. 
This allows your program to execute at full speed until it hits 
the breakpoint, rather than requiring the debugger to single¬ 


step and check the breakpoint conditions at every instruc¬ 
tion. 

CV/ICEing for DOS costs $129 and is compatible with 
Microsoft C/C++ v7.0. A free update will be sent to all 
registered users when CodeView 4.1 support is available. For 
more information, contact The Periscope Company, 1197 
Peachtree Street, Atlanta, CA 30361, (800) 722-7006 or 
(404) 875-8080; FAX (404) 872-1973. 
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Micrografx Ships OS/2 Porting Tool 


Micrografx Mirrors, a developer’s toolkit for porting Win¬ 
dows applications to OS/2, is now available. Mirrors allows 
developers to maintain a single set of source code for both 
Windows and OS/2 versions of their applications. Mirrors is a 
32-bit DLL that emulates Windows under OS/2, enabling Win¬ 
dows applications to run as native OS/2 applications. Mirrors 
includes support for 16-bit applications, automated help file 
conversion, support for bitmaps, cursors, and icons, DDE, clip¬ 
board access, and D0S3CALL interrupt and Int 21h support. 


Micrografx will provide sales, marketing, support, and 
training to assist third-party, independent software vendors 
and corporations in porting applications from Windows to 
OS/2 using the Micrografx Mirrors toolkit and the Mirrors DLL 
This assistance will include porting analysis and project plan¬ 
ning, telephone support, and consulting services. 

Micrografx Mirrors costs $495. For more information, con¬ 
tact Micrografx, Inc., 1303 Arapaho, Richardson, TX 75081, 
(214) 234-1769 or (800) 733-3729; FAX (214) 234-2410; 
Telex 650-3093890. 


HALO Library Offers Portable Image Manipulation 


HALO Imaging Library is a new, platform-independent 
library from Media Cybernetics that lets developers add im¬ 
aging capabilities to their applications. The library will be 
available for Windows, OS/2, Macintosh, UNIX/Motif, and 
UNIX/Open Look. The library provides more than 100 imag¬ 
ing functions and commands, supporting reading and writing 
images in several file formats and image manipulation in 
memory. 

The library supports reading and writing TIFF, JPG, GIF, 
TGA, PCX, BMP, CUT, and PICT files, and can generate EPS files. 
Image conversion functions let you convert images from one 


class to another, such as from color to grayscale. Image en¬ 
hancement functions let you adjust and refine brightness, 
contrast, and gamma characteristics, and provide special ef¬ 
fects such as blur, pixelize, sculpt, emboss, and overlay. 
Transformation functions let you rotate, transpose, flip, or 
spatially distort images. 

HALO Imaging Library for Windows costs $595 for a 
single workstation license. For more information, contact 

Media Cybernetics, 8484 Georgia Avenue, Silver Spring, 
MD 20910, (301) 495-3305; FAX (301) 495-5964. 


Programmer's Editor Adds NT Support 

SpeedEdit vA.06 is a programmer's text editor now avail¬ 
able for Windows and Windows NT. SpeedEdit is also avail¬ 
able in both graphics and character mode versions for DOS, 
AIX on the RS6000, HP-UX, SCO UNIX, UNIX, SunOS, Dynix/ptx, 
and MPE/iX. The Windows NT and X-Windows versions offer 
a new customizable button bar for quick access to common 
commands, additional facilities for customizing mouse ac¬ 
tions, an enhanced command language, and an increase in 
the maximum number of open windows to 64. 

The new version includes an improved help facility with 
a learn mode that provides a popup help box describing 
each command when it is executed for the first time. 


Likewise, the user can recall help for the most recent com¬ 
mand. A new librarian capability lets users customize Speed¬ 
Edit to automatically check files out of their favorite source 
code control system and check them back in when they are 
done compiling and testing. The new version also supports a 
“modal keyboard” capability to allow key remapping to simu¬ 
late vi. 

Single-user versions of SpeedEdit cost $225 for DOS and 
Windows, $245 for Windows NT, and $395 for UNIX versions. 
For more information, contact Bradford Business Systems, 
Inc., 23151 Verdugo Drive, Suite 114, Laguna Hills, CA 
92653, (714) 859-4428; FAX (714) 859-4508. 


WCSC Updates Multitasking DOS Kernel 

MTASK is a preemptive multitasking kernel for DOS. It 
provides real interprocess communication (IPC) and a task 
can block until it receives its IPC message. Tasks can sleep 
for a specified period of time or indefinitely until awakened 
by some other task. Your application can either link to the 
multitasking libraries or link to the multitasking TSR at run¬ 
time. 

MTASK v3.0 includes all the source for the multitasking 
libraries. It also includes the WCSC Standard Library, which 


contains several reentrant functions for file I/O, memory 
management, and BIOS access. It also includes calls to 
simplify creating TSRs. The MTASK kernel is now aware of 
both Windows and the DOS task switcher. MTASK applica¬ 
tions can run under Windows, MS-DOS, or Desqview. 

MTASK costs $299.95. For more information, contact 
WCSC, 2470 S. Dairy Ashford, Suite 188, Houston, TX 
77077, (800) 966-4832 or (713) 498-4832; FAX (713) 568 
3334. 


Distinct Offers 3-in-1 TCP/IP SDK 

Distinct Corporation has released the professional version 
of Distinct TCP/IP for Windows, version 3.0. The package in¬ 
cludes the Windows Sockets API vl.1, Distinct’s TCP/IP Kernel 
API for Berkeley-style Sockets (TCP, UDP, ICMP, Telnet and 
FTP), and Distinct RPC, a complete ONC RPC/XDR toolkit for 
Windows. The package supports a wide range of program¬ 


ming languages, including Borland and Microsoft C/C++, 

Visual Basic, and Turbo Pascal. 

The Professional Edition SDK costs $495; existing users 
can upgrade for $200. For more information, contact Distinct 
Corporation, P.O. Box 3410, Saratoga, CA 95070-1410, 
(408) 741-0781; FAX (408) 741-0795. 
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Quintus Brings Prolog to DOS and Windows 


QP/386 is a Quintus Prolog implementation for DOS and 
Windows that is fully compatible with Quintus Prolog v3.1 on 
UNIX systems. The product uses the Quintus Object Format, 
is embeddable in C, provides incremental compilation of 

Prolog source code, includes the Quintus 7 port debugger, 
has access to the Quintus Prolog Library, and offers 32-bit ad¬ 
dressing. QP/386 is designed to be used with the WATCOM 

C/386 compiler to develop applications in a combination of 

Prolog and C 

QP/386 costs $995. Programmers can develop on either a 

386/486 or a UNIX platform, then run the completed applica¬ 
tion on either platform. For more information, contact Quin¬ 
tus Corporation, 2100 Geng Road, Suite 101, Palo Alto, CA 

94303, (415) 813-3800; FAX (415) 494-7608. 


Portability Tool Adds Character Set Independence 


The Universal Component System (UCS) is a development 
system that provides a common programming API across 
many platforms. The new UCS release adds a common char¬ 
acter set API across platforms that support Unicode, Macin¬ 
tosh WorldScript 1 and II, Windows DBCS, and a variety of 
single-byte encoding schemes, including ASCII and ANSI. The 
package includes portable APIs to handle the different for¬ 
mats for date, time, currency, and numerics, as well as the 
sorting requirements of each language. The package also in- 

dudes portable, internationalized versions of the standard C 
string manipulation routines. 

UCS prices range from $3,500 to $10,000 per develop¬ 
ment system depending on the platform and configuration. 

Runtime licenses require a one-time royalty fee. For more in¬ 
formation, contact Software Transformation, Inc., 1601 
Saratoga-Sunnyvale Road, Suite 100, Cupertino, CA 95014, 

(408) 973-8081; FAX (408) 973-0989. 


AC/S Brings 3D Modeling to Windows 



Personal ACIS and Professional ACIS are products 
designed to help Visual Basic developers create 3D modeling 
and 3D visualization applications for Windows and Windows 

NT. The products provide a complete environment for creat¬ 
ing high-precision models and photo-realistic images of 
mechanical objects, structures, and landscapes. 

Personal ACIS provides an interpretive language 
(Scheme), an interactive rendering subsystem, 2D and 3D 
geometry construction facilities, full 3D surface (NURBS), and 
solid modeling support. Professional ACIS includes the Per- 

sonal ACIS subsystems and adds enhanced model access 
and application redistribution rights for 3D application 
developers. 

Personal ACIS costs $995; Professional ACIS costs $5,000 
for three developers and $2,500 for each additional 
developer. The product also has a royalty fee of $250 per 
unit For more information, contact Spatial Technology, Inc., 

2425 55th Street, Building A, Boulder, CO 80301, (303) 449- 
0649; FAX (303) 449-0926. 


NETROOM 3 Offers 32-Bit API 



NETROOM 3 is a new version of a memory management 
package for configuring DOS memory. The new version con¬ 
tains ■cloaking,” which can move BIOS, video BIOS, screen 
savers, disk caches, RAM disks, screen accelerators, and 
other utilities into extended memory, freeing up convention¬ 
al memory. The new product lets programs run in 32-bit 
protected mode while remaining DOS compatible. The Cloak¬ 
ing API is included with each copy of NETROOM 3 for 
developers who want to produce 32-bit applications, drivers, 

and TSRs that use virtually no conventional memory. The ap¬ 
plication will require the presence of Helix's 386/486 
memory manager to run. 

NETROOM 3 costs $99 for a single-user license. 

Developers can also obtain licenses for shipping Helix's 

386/486 memory manager with their products. For more in¬ 
formation, contact Helix Software Co., 47-09 30th Street, 

Long Island City, NY 11101, (800) 451-0551 or (718) 392- 
3100; FAX (718)392-4212. 
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vxBase Adds Image and Sub-Index Support 


vxBase is a Visual Basic database management program 
that handles xBase files using Clipper-style indexes. Now. vx¬ 
Base v3.0 supports storing images in a memo file, allowing 
database retrieval of photos and graphics. The new version 
also has the ability to create subindexes to define a subset 
of the main database, speeding up particular kinds of access. 
vxBase also includes user-definable error messages, making 


it easier to localize the product vxBase is already available 
in Dutch, English, French, German, Italian, and Spanish. 

The shareware version of vxBase costs $60 and the full 
developer's version costs $295. For more information, con- 
tart Abacus Systems, 12 South Main, Suite 204, Minot, ND 
58701, (800) 992-0616 or (701) 838-4686; FAX (701) 838- 
4932. 


Spreadsheet Controls Support Both VB and VC 


FarPoint Technologies is offering two spreadsheet con¬ 
trols that support both Microsoft Visual Basic and Microsoft 
Visual C++: Professional ToolBox and Visual Architect You 
can use Visual Architect as a functional spreadsheet, to ob¬ 
tain variable lines of data from the user, or simply to display 
tables of information from a database. The control lets you 
change the width and height of columns and rows, as well 
as the font, color, and data type for any cell. Cell types in¬ 
clude edit, date, time, integer, float, static, formatted data, 
combo box, button, and picture. Cells support formulas. 

Professional ToolBox includes not only a spreadsheet con¬ 
trol, but formatted edit controls, a tool bar, a status bar, 3-D 


effects, view pictures with animation, and an enhanced 
listbox. New features include virtualized database support, 
full sorting, a checkbox cell type and owner-draw cell type, 
borders for cells or rows and columns of cells, multiple-block 
selects, overflow of text to the next column, grid color con¬ 
trol, drag-and-drop, and full clipboard support. 

Visual Architect costs $245 and Professional ToolBox 
costs $345. For more information, contact FarPoint Tech¬ 
nologies, Inc., P.O. Box 309, 75 Walnut Street, Richmond, 
OH 43944-0309, (614) 76 5-4333; FAX (614) 765-4939. 


WATCOM Releases C/C++ 32 v9.5 

WATCOM has released a new version of their 32-bit 
C/C++ compiler, which supports DOS, Windows 3.x, OS/2 2.x, 
Windows NT, Win32s, and AutoCAD ADS/ADI. The new C++ 
compiler adds support for templates and exceptions, the 
most significant additions to the evolving C++ language 
standard. Borland C++ and Zortech C++ support templates, 
but not exceptions. Microsoft C++ supports neither templates 
nor exceptions. The new compiler can also optimize code 
correctly to take advantage of the RISC-style instruction 


scheduling in the new Intel Pentium chip. The new style of 
optimization is necessary to fully exploit the speed potential 
of the Pentium. 

WATCOM C/C++ 32 costs $599. It is a single package that 
supports development under DOS, OS/2 2.x, or Windows NT. 
Upgrades from WATCOM C/386 v9 cost $199 and are avail¬ 
able directly from WATCOM. For more information, contact 

WATCOM, 415 Phillip Street, Waterloo, Ontario, Canada 
N2L 3X2, (519) 886-3700; FAX (519) 747-4971. 


Sax Provides Windows Serial Communications 


Sax Comm Objects is a new C/C++ function and class 
library for building serial communications applications for 
Windows. The package provides the same functionality in 
multiple forms: a C function library, a C++ class library, and a 
custom control for Microsoft Visual C++. 

The package supports background file transfer using X- 
Modem, YModem, YModem-g, ZModem, Kermit, and Compu¬ 
Serve B+ protocols. Sax Comm Objects can also provide color 
terminal emulations, including ANSI, TTY, VT100, Vt52, with 


scrollback buffer, automatic file capturing, mouse selection, 
and clipboard support. The package also offers event notifica¬ 
tion, automatic lookup strings, and low-level control for 
handshaking, flow control, and special communications 
protocols. 

Sax Comm Objects costs $299. For more information, con¬ 
tact Sox Software, Callaerstraat 23, B9100 Sint-Niklaas, Bel¬ 
gium, 32-37663264; FAX 32-3-7781405; CIS 75470,1403. 


Synaptix Offers Visual C++ Training 

Synaptix is now offering Advanced Object-Oriented Win¬ 
dows Programming Using Visual C++, a two-week, instructor- 
led course to train C programmers to create large-scale, 
object-oriented, Windows programs using Visual C++ and the 
Microsoft Foundation Class Libraries. The first week of the 
course explores object-oriented C++ programming, while the 


second week focuses on applying the Microsoft Foundation 
Class Libraries to Windows programming. 

The course is available now for on-site presentation and 
costs $34,000 to $40,000, depending on the number of par¬ 
ticipants. For more information, contact Synaptix, 4739 
University Way NE, #486, Seattle, WA 98105-4412, (800) 
800-4963. 


Page 90 


Windows/DOS Developer’s Journal 


May 1993 









Readers' Forum 


Code Correction 

To: Ron Burk 

I recently received the March issue 
of Windows/DOS Developer’s Journal, and 
have implemented my own Real-time- 
dock interrupt handler using the code 
John Reynolds published in his article, 
“Real-World Device Control Using PC 
Hardware.” Of course, I modified it to 
my own requirements. Anyway, I was 
wondering if he made a mistake in the 
code. On page 10, Listing 1, in the 
DisableRtcInts() function, he does an 
outportb(IMRZ,inportb(IMR2) & 
!RTC_MASK) The mistake that I think 
he made was doing the !RTC_MASK. 1 
believe he wanted ~RTC_MASK, so it 
would look like: 

outportb(IMR2,inportb(IMR2) & 

~RTC_MASK); 

I myself have sometimes gotten the 
two NOTs mixed up (using the exclama¬ 
tion not [logical not] instead of the tilde 
not [physical not]). Am I correct in this 
assumption? 

Dan Corritore 70243,1110 

I talked to the author, and you are ex¬ 
actly right; we will correct the code disk. 
Thanks for catching this, Dan. —rib 


Ron, 

There is a potential problem with 
the solutions described for freeing brush 
memory in your March 1993 Readers' 
Forum. When running multiple instan¬ 
ces of a program, changes to the class 
brush in one affects them all. 

To avoid this, register the class with 
a NULL brush when you know you’re 
going to be changing the background. 
Then in response to WM_PAINT mes¬ 
sages, create a brush, set it as the 
background brush, paint the window as 


usual, reset the class brush to NULL, 
and delete the one created earlier. For 
example: 

void PaintFunction(HWND hWnd) 

{ 

PAINTSTRUCT ps; 

HDC hDC; 

HBRUSH hb; 

hb = CreateSolidBrush(RGB(r,g,b)); 

SetClassWord(hWnd,GCW_HBRBACKGROUND,hb); 

hDC = BeginPaint(hWnd,&ps); 

// do your painting 

EndPaint(hWnd,&ps); 

SetClassWord(hWnd,GCW_HBRBACKGROUND, 
(HBRUSH)NULL); 

DeleteObject(hb); 

} 

Sincerely, 

Peter D’Agostino 
The Computech Group, Inc. 

9285 Lerwick Drive 
Dublin, OH 43017 

I was out of my depth on this topic, 
so I had to get Paul Bonneau to ex¬ 
plain it all to me. He agreed, as you 
have pointed out, that storing the 
brush in the window can cause 
problems - if two instances of the pro¬ 
gram are running and the first shuts 
down, it will delete the brush and the 
other instance will try to use a brush 
that is no longer there, for example. 

Paul also pointed out that you 
probably want to solve this problem, 
not in WM_PAIN T, but in 
WM_ERASEBKGND. Your solution 
works most of the time, because you 
set the brush before calling Begin- 
Paint(), which typically generates a 
WM_ERASEBKGND message. How¬ 
ever, your window can also get a 
VJMJERASEBKGND message under 
other conditions. Also, Paul noted that 


WMJCONERASEBKGND uses the 
background brush as well, so it 
sounds like one solution that would 
cover all the bases might look like 
this: 

case WM_ERASEBKGND : 

case WMJCONERASEBKGND : 

OldBrush = SetClassWord(Window, 

GCW_HBRBACKGROUND,MyBrush); 
Result = DefWindowProc(/* args */); 
SetClassWord(Window,GCW_HBRBACKGROUND, 
OldBrush); 
return Result; 

The Petzold example (colorsl.c, 
the source of the original question) 
sidesteps the problem by not allowing 
more than one instance of the pro¬ 
gram to run. That’s certainly the easy 
way around more than a few 
problems, and one that too many ap¬ 
plications take, reducing the ad¬ 
vantages of having a multitasking sys¬ 
tem. Thanks to Peter for pointing this 
out, and to Paul for filling in the gaps 
in my understanding, -rib 


Editor, 

Last month, I received my first copy 
of your Windows/DOS Developer's Jour¬ 
nal (Vol. 4, No. 2). For the past 10 years, 
my primary job has been that of a 
technical writer in some relatively high- 
tech firms in this area. In addition, I 
have also been a PC enthusiast, oc¬ 
casional programmer, system installer, 
PC guru to some, and telephone sup¬ 
port person. 

Since receiving your magazine, I 
have tried several times to read and 
understand it, without success. I 
thought that this magazine would help 
me learn more about Windows 
development. However, this magazine 
seem to be written by experts for ex¬ 
perts, with little concern for using 
everyday English. 
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I could not find a statement of mis¬ 
sion or statement of goals, and from 
the context I can only conclude that the 
only intended audience is that of expert 
developers. If I was an expert, I doubt 
that I would need to read this 
magazine. It is my opinion that this 
magazine would be able to reach 
several levels of audience if the authors 
did a more thorough discussion of their 
intent, less rambling, more defining of 
terms, and less use of jargon such as 
“instancing." 

Another thing that I noticed was a 
lack of “letters to the editor." Either no 
one sends compliments or complaints, 
or you are not open to “airing your 
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BACK ISSUES 
AVAILABLE 


Missed an Issue? 
Call today to get 
your copy. 

Ask for a complete 
listing of available 
back issues — we’ll 
send you a listing 

FREE! 


CALL 913 - 841-1631 
fax 913 - 841-2624 


dirty linen.” Please cancel my subscrip¬ 
tion until you produce a magazine that 
better meets my non-expert needs. 

Don Dickert 
5860 Evergreen Lane 
Shoreview, MN 55126 

I am disappointed that you 
managed to subscribe without seeing 
a statement of our mission; I believe 
most or all of our marketing materials 
have used the slogan “Advanced, 
Serious, Technical” for some months 
now, which describes our positioning 
pretty well. Over half of our audience 
has been programming for more than 
a decade and we definitely prefer to 


cover hands-on, advanced topics that 
you can't find in books or other 
magazines. We do provide introduc¬ 
tory material on technical areas, such 
as Rob ReicheTs introduction to Win¬ 
dows NT security, but the writing in¬ 
variably assumes that the reader is an 
experienced programmer. 

Since I provide most of the techni¬ 
cal editing for the magazine, I take to 
heart your criticism about the quality of 
the writing and the use of jargon. Jar¬ 
gon, although the word may have 
negative connotations, is absolutely 
essential in technical writing. Without 
it, descriptions of common activities 
can consume hundreds of words 


JOBS 

PM 
Mac 
Oracle 
Progress 
Windows NT 
Smalltalk 
Case 
OS/2 

Our midwest Clients are using 
Leading edge technology you thought 
you'd only see on the coasts. Discover the 
heartland, our quality of life and our 
commitment to technology. 

Employer Paid fees only. 

All recruiters are certified by the NAPC. 

Brad Moore, C.P.C. 

256 N. 115th Street, Suite 1. Omaha, NE 68154-2521 
(402) 334-7255 Fax (402) 334-7148 
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Productivity Tools--Send For Our 
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Springtime Software 
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SpeakEz Class Libraries 
■ 

WINDOWS C++ DEVELOPERS! 
Easily Incorporate Sound into 
Windows MultiMedia Applications 


□ Media Control Interface (MCI) class 
provides full support for Waveform, 
MIDI, and CD-ROM devices. 

□ Librarian Class provides sound file 
storage with built-in Data Compres¬ 
sion 

□ $99 for Static Libraries and DLLs. 
$250 for source code license. 

No Runtime Royalties! 

□ Supports Borland C++ 3.1 and 
Microsoft C++ 7.0 / Visual C++ 

Sound <hioJuzons 

P.O. Box 6625, Holliston, MA 01746 
_ (508) 643-2882 _ 
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Windows 
Developer Jobs 


Specialists in jobs for software 
engineers in leading edge technology. 
Windows, PM, GUI, Languages, AI, 
Mac, CASE, Video, Realtime. 
Nationwide contacts with both large 
and small companies including equity 
startups. Many of our clients develop 
and publish commercial software 
products. Managed by graduate 
engineers. Never a fee to an 
applicant. 

1-800-231-5920 



Scientific Placement, Inc. 

SPI-8, Box 19949, Houston, TX 77224 (713) 496-6100 
SPI-8, Box 71, San Ramon. CA 94583 (510) 733-6168 
SPI-8, Box 4270, Johnson City, TN 37602 (615) 926-6188 
Fax: 713-496-6802 please use Fine Setting on Fax 
Email: Ascii preferred: Internet LSH@Scientific.com; 
\^ompuserve: 71250,3001; Genie: D.SMALL6 _ > 
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FAST TEXT SEARCH 
for C / Windows 



Create High 
Performance 
Network 
Applications 
FASTI 

Now Shipping 
Version 2.03! 

60 Day Money 
Back Guarantee! 


0 Shared DLL resources 
supports multiple applications 
and instances. 

0 Full post processing support 
& notification via messages 
(wait, no-wait, and polled). 

0 Complete NCB and attached 
data buffer functions simplify 
memory management. 

0 Complete documentation and 
on-line API help reference. 

0 Control panel utility allows 
dynamic DLL configuration. 

0 WINDOWS.TXT compatibilty 
for DOS support. 

0 No royalties, full source with 
demos. Now only $129.00! 


SIGMA SOFTWARE RESEARCH 

702 Windridge Dr., Atlanta, GA 30350 

9 TEL/FAX (404) 992-0536 

Also available at the Programmer's Connection! 
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The fastest, easiest and most versatile way to 
add full text search capabilities to your C and 
Windows applications, FAST TEXT SEARCH 
for C is a function library enabling rapid 
searches of both structured and unstructured 
textual data with low overhead/memory 
requirements, low cost and high efficiency. 
Great with CodeBase, SoftC, AccSys, etc. 
No Risk 30 day Money Back Guarantee 

Order-(800) 334-8099 
Only $189.00 

Windows/DOS Developer’s Journal Special includes 
UltraSearch & Free 2 Day Shipping 

DOS (Microsoft, Borland) and OS/2 libraries 
& Windows DLL, royalty free integrator license, 
eadocu '* 


complete printed documentation, sample 
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programs & free technical suj 
MasterCard/COD/Qualified 
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Index Applications Incorporated 

k\ 8546 Broadway, Suite 208 
San Antonio, TX 78217 USA 
512 / 822-4818; fax: 512 / 828-5074 


RELIEF 

from TLINK and LINK 
Headaches 

OPTLINK for Windows provides 
Borland developers with higher capacity 
linking intra-segment far call to near 
call conversions and Windows 
exe-packing. You get faster, more 
efficient programs. Microsoft 
developers get linking several times 
faster than LINK, Windows 
exe-packing and innovative build-time 
debugging features. 

It eliminates the 2nd pass of RC and 
generates DOS, Windows, and OS/2 
programs from C, C++, Basic, and 
Fortran objects. Ask us about our OPTLIB 
Superfast Librarian too. 30-day MBG. 

SLR Systems, Inc. 

(412) 282-0864 
Fax (412) 282-7965 
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Visual Basic, 
BASIC, and PDS 
programmers! 

General Purpose Toolboxes 
Graphics 

^sSfleff Design 
Cemmunkations 
„ laser Printing 
Sdentific Applications 
: fSIPs and more! 


Crescent Software offers many tools for 
QuickBASIC, PDS, and Visual Basic. All 
products include complete source code, 
free technical support, and royalties ore 
never required! K»unMius4f»iD(M0P»aiAas 




CRESCENT SOFTWARE. INC. 

11 BAILEY AVENUE 
RIDGEFIELD, CT 06877-4505 
2034385300 FAX 203431 4626 


Does your company provide 
tools, products, or services 
for advanced Windows 
programmers? 

Then reach over 27,000 
serious programmers in: 

Windows"/DOS 

□ DEVELOPER'S JOURNAL 

Call 913-841-1631 today for 
information about advertising 
opportunities in Windows/DOS 
Developer’s Journal. 

Advanced. Serious. 
Technical. 

Brian Osborn - Continental Europe. 

Ed - East Donna - Midwest Edwin - West 


TUB “ is FASTEST! 



RCS™ 4.2 PVCS™ TUB" 1 3.0 TUB ” 5.0 


Times are to update a 45K library on a PC/XT. PVCS and TUB 3.0 are 
from Sept 87 PC Tech Journal. MKS RCS 4.2 and TUB 5.0 are newer 

TUB™ is BEST! 

"Do not be fooled by the fact that this is the 
least expensive of the five packages reviewed 
here - TUB has features and power to spare" 
John Rex, Computer Language 
“TUB is a great system’’ J. Vallino, PC Tech J 

• Full-Featured Version Control for Software 
Professionals. Check-in/out locking. Branching. 
Keywords. Wildcard and list-of-file support. Can 
merge parallel changes and undo intermediate 
revisions. Network and WORM support. Main¬ 
frame compatible deltas for Pansophic, ADR, IBM, 
etc.. Integrates with Opus " MAKE & Slick 1 ' MAKE. 

MS-DOS $139, OS/2 $195 + shipping visa/MC 
5 station LAN license $419 (OS/2 $595), call for other sizes 

BURTON SYSTEMS SOFTWARE 

PO Box 4156, Cary, NC 27519 (919)233-8128 

□ Request 137 on Reader Service Card □ 


C and C++ DOCUMENTATION 


! AUTOMATED DOCUMENTATION ! 

• C-CALL ($69) Graphic-tree of caller/called 
functions, cross-ref, file/function index. 

• C-CMT ($69) Creates/inserts/updates 
comment-blocks for each function, listing 
the functions and identifiers used by it. 

• C-METRIC ($59) Counts path complexity, 
counts comments, code, ’C' statements. 

• C-LIST ($69) Lists and action-diagrams, 
or reformats into standard formats. 

• C-REF ($59) Creates cross-reference of 
local/global/define/parameter identifiers. 

• SPECIAL : C-DOC ($199) All 5programs 
integrated as DOS program (<15,000 lines) 

• NEW! C-DOC Professional ($299) 

DOS, OS/2, Windows. 3-ring binder/case. 
Processes 150,000 lines, deterred reports. 

• 30-DAY Money-back guarantee CALL NOW 

SOFTWARE BLACKSMITHS INC, 

6064 St Ives Way, Mississauga 

ONT, Canada Voice/Fax (4161-858-4466 

L5N-4M1 _Dernos/BBS (41bi-858-l9l5 


see AD INDEX for our larger ad 



We Understand The 
Programmer's Mind 


When the country's top firms look for the 
best developers available, they turn to 
Bateman. Why? Because we specialize in 
Microsoft Windows, NT, OS/2 and Macin¬ 
tosh recruiting nationwide. So if it's time for 
a career move, give us a call. We under¬ 
stand your skills, and the marketplace for 
them... we understand you. 

□Bateman Inc. 

5847A Uplander Way 
Culver City, CA 90230 
Tel: 310-641-4100 Fax: 310-641-2900 
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Wisconsin's largest professional services firm, Com¬ 
puter People Unlimited, has continually bucked the 
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in a weak economy. Because of our unique 
position we con offer you technical challenges in o 
city known for its beauty and old world charm. As 
o Software Engineer, you will design, code ond 
test MS-Windows based scientific applications us¬ 
ing C. Coll Julie Endlich at (414) 225-4000 or 
1 (800) 527-8462. You moy also send your 
resume in confidence to: Computer People Unlim¬ 
ited, Dept.DJ, 732 N. Jackson St., Milwaukee, Wl 
53202. Fox: 414-225-4011.E0E. 
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instead of a few sentences. For ex¬ 
ample, consider all the implications 
summed up in the word “selector" for 
a Windows programmer. I seriously 
doubt anyone would enjoy an article 
on Windows memory management that 
never used this particular jargon word. 

Jargon is not bad in itself; the prob¬ 
lem is deciding when and where to 
apply it. That judgment has to be 
made based on experience and 
familiarity with the audience. I believe 
that I am doing a better job as techni¬ 
cal editor now than when I first started, 
but I know I have plenty of room for 
improvement. Also, your complaint has 
prompted me to consider that, as we 
continue to grow and reach a broader 


audience, using parenthetical text and 
introductory sidebars to deal with 
some kinds of jargon may be more im¬ 
portant. We will never, however, be a 
magazine for inexperienced program¬ 
mers, and we won’t ever remove so 
much jargon that the articles become 
tediously verbose to experienced DOS 
and Windows programmers. 

As to your last comment, we actual¬ 
ly run a fairly high percentage of the 
mail we receive, so long as it arrives 
as a physical letter, FAX, or in the 
wdletter@rdpub.com mailbox. We just 
don’t get much mail through those 
channels. Also, sometimes it comes 
down to dropping the letters section 
or dropping an article, and then I 


usually vote to keep the article in. Of 
the letters we do receive, I tend to 
favor running complaints over compli¬ 
ments. Complaints are not “dirty 
linen," but an opportunity to under¬ 
stand and solve problems, and im¬ 
prove our products and sen/ices. 

Thanks for giving us your criticisms, 
even though they are in parting. Clear¬ 
ly, we are not the right magazine for 
you now. However, we will continue to 
improve and you will continue to slog 
through the tar pit of Windows 
programming, and perhaps if you pick 
up a copy in another year we may 
have arrived on common ground, -rib 
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The Art of Visual Basic Programming ™ 

This amazing new book by J. D. Evans, Jr. unlocks 
the secrets of Windows and Visual Basic 
application design and programming. It explains 
Windows design from a unique and easy to 
understand perspective. Smart Objects, Hybrid 
Objects, Control Coupling, Events, Focus, Event 
Triggering, Visibility, Form and Module Code 
Placement, DLL Parameter Passing, Variable 
Scope, Strings, and Structures are described and 
explained. Enlightening allegories and annecdotes 
make this one of the most unusual and informative 
Windows books ever written. This book is the 
Rosetta stone for Windows and Visual Basic! 


Book: $29.95 Companion Disk: $9.95 
ETN Corporation 
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SpyWorks-VB 

For Visual Basic™ - Windows 

SpyWorks-VB allows you to do virtually 
anything in Visual Basic that is possible 
using other languages such as C. It 
includes controls that easily subclass 
VB forms and controls, detect keyboard 
events, and support callback functions. 
SpyWorks includes debugging tools to 
view message and event history, detect 
API parameter errors, Browse Windows 
memory and resources, and retrieve 
information about any window, form or 
control in the system. 

SpyWorks-VB is only $129 + $5 s&h ($15 
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Macro 
Language 
"To Go" 


I Easily embed Netlogic’s full-featured 
procedural language engine in your 
Windows application — at a fraction of 
the time and cost of developing it 
J yourself. Seamless integration. Full 
basic syntax. Integrated editor and 
debugger. Extendable and modifiable. 
For more information: Netlogic Inc., 
915 Broadway, New York, NY 10010. 
1-800-638-0048. Fax:(212) 533-9090. 

ProMacro 
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□ Request 136 on Reader Service Card □ 


2 

a 

SmartHcap professional memory man¬ 

£ 

agement library and debuggins toolkit (for¬ 
merly OptiMem from Applegate Software) 
is the only tool avail, w/ both fast, optimum 
mem mgmt and comprehensive error de¬ 

r 

tection. Combination of variable and fixed- 

to 

E 

sizeallocators maximizes both performance 
and flexibility. Incl ANSI C'malloc" and C++ 
"new," + many other APIs. Fixes selector 

i/i 

consumption, overhead, granularity, frag¬ 

V 

mentation, and DGROUP depletion. Mini¬ 
mi zes d i sk thrash i ns by localizing data struc¬ 


tures in their own heaps. Uses just 12K at 

o 

runtime. Detects double-freeing, mem over¬ 

rH 

writes, leakage, invalid parameters, wild 

< 

pointers, etc. Programmatic error handling 

t—1 
& 

and heap-walking. Works w/ EXEs, DLLs, & 
device drivers. Bullet-proof reliability, 

0 

"Who's who" user base. 166 page manual. 

0 

No royalties. Source available. $395 

+ 

CALL FOR FREE WHITE PAPER! 

U 

800-441-7822 

r-H 

FAX 206-525-8309 

rti 

e 

MicroQuill 


Software Publishing, Inc. 


□ Request 310 on Reader Service Card □ 


CD 


EACH TOPIC 
DISK 

CONTAINS 

HUNDREDS OF 
APPUCATIONS 

THOUSANDS 
OF FILES 

MANY WITH 
FULL SOURCE 
CODE. 


KNOWLEDGE MEDIA 

RESOURCE LIBRARY 


ROMs 

GRAPHICS 

ANIMATION, PAINT. CONVERTERS. 
FRACTAL, DRAWIN©, JPEO. 
MAPPING. «F. PLOTTING. PAINT. 

AUDIO 

CONVERTERS, MttX, EDITORS, x xL 
MIXERS, MOOS, MUSIC, PLAYERS, 

snd, speech Packers, voc, wav 


MULTIMEDIA 

AVTHOWNO SYSTEMS, P8ES07TAT1ON 

powers, ccnuni media ubraries 


ORDER DESK: (800) 78 CD ROM 
ORDERS BY FAX (916) 872-3826 
VISA and MASTER CARD or COD 
436-B Nunneley, Paradise, CA 95969 

□ Request 118 on Reader Service Card □ 


SDLC, HDLC OR X.25 
SUPPORT OIM THE PC 

Use the Sangoma SDLA card to 

provide exceptionally cost effective, full 

featured, stable and easy to use link 

support for your product or project. 

• Line speed to 180kbps 

• Compatible with all operating 
systems and environments 

• Operating statistics and built in 
datascope make your product easy 
to configure and debug 

• Menu driven test program included 

• Primary and secondary SDLC with 
multiple addresses 

• HDLC LAPB, LAPD, NRM mode 

• CCITT 1988 X.25 implementation 

• High level interfaces for X.25 under 
DOS, UNIX, Windows, OS/2. 

S3TI^0 ITltl Technologies Inc. 
Tel: (416) 474-1990; (800) 388-2475 
FAX: (416) 474-9223 


REAL-TIME MULTITASKING 
DEVELOPMENT ON PC 


MTXc Kernel is All you need to build 
Real-Time Multitasking applications 
=* Simply and Effectively «= 

- Preemption, non-preemption, piffles, inter-task 
mails, messages, semaphores 

- Distributed proqessing 

- Serial communication port up to 115,200 baud rate 

- Coded in 100% 'C' and occupies less than 8K 

- Plenty of sample programs, complete manual 

- No royalties 

Use Borland* or Microsoft, compilers, debug with 
Turbo Debugger., CodeView.. 

Use MTXView. kernel monitor to examine kernel's 
internals; Tasks, mails, messages, semaphores, 
ready and timer queues. j \ ! j \J 

Borland or Microsoft pre-compiled libraries :$129.00 

Full source code . . . .: $395.00 

| Call for FREE fully operational DEMO disk! \ 

HI! IMPULSE SYSTEMS _ 

2724 Bonnie Drive (800) 2 KERNEL 

Santa Clara, CA 95051 phone/fax (408) 244-6225 

□ Request 140 on Reader Service Card □ 
May 1993 


wasting time and 
money programming 
TCP/IP for Windows 

Socket programming has been superceded by 
network middle-ware for Windows that encapsulates 
TCP/UDP/TELNET & TFTP in an easy-to-use server! 

GENISYS Comm Pack++ 

► 4-function DLL for your C/C++/Fortran app 

► NEW Visual Basic custom controls too! 

► Quickly embed TCP/IP comm in your apps 

- share files and messages with UNIX hosts 

- turn your PC into a sophisticated server 

► Binary compatible with most TCP/IP stacks 

► No Royalties! Evaluation Kit available. 

For Windows & data networking support contact: 

GENISYS Comm, Inc. 

314 South Jay St., Rome, NY 13440 
(315)339-5502 
GCP++@>GENISYS.com 
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MICROSOFT* 

WINDOWS- 

COMPATIBLE 



Tools for Novell’s Btrieve* 

Bsupport III Bsupport II 

Bed it 3.0 - Btrieve file viewer/editor. 

Banalyze 2.0 • Btrieve app. debugger. 

Bruit 2.2 - BUTIL replacement plus source. 
Bcreate 2.0 - file creation utility. 

Bcltcck 2.0 - Btrieve file analyzer. 

Xsupport 1.0 - build data dictionary 
(.DDF) for Access, OV, 
Crystal Rpts. 

Xport 2.0 - export/import CDF, SDF, 
dBASE. 

Call for information on additional 
products and FREE demo! 

Information Architects, Inc. pj, : (flgo) 359-2721 
3130 Pine Tree Road (517) 887-8000 

Lansing, MI 48911 Fax: (5171 887-2366 
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Graphics & Timing Tools 


BGI Printer Driver Toolkit - bgi printer 
drivers for Borland's BGI graphics library. Epson/IBM 9 
pin, Epson/IBM 24 pin, LaserJet, DeskJet, PaintJet, 
Postscript, HPGL, DTP file formats, ot'rors. Extensive 
color device support. Load our drivers with BGI's 
initgraph and aet full hardcopy device resolution! 
Supports TC, TC++, BC++, Turbo Pascal, Borland 
Pascal real and protected modes. $129.95. 

BGI For Windows - BGI compatible interface to 
Windows 3.x GDI. Port your Borland DOS BGI 
graphics routines effortlessly to Windows. Includes 
complete high resolution hardcopy support. Supports 
Borland Windows compilers. $129.95 
PC Timer Tools - Ideal for execution profiling, 
data acquisition, process control applications. 
Extensive functions for precision timing, delays, 
alarms, thread scheduling, timer tick management. 
Supports TC, TC++, BC++, MSC, Intel CB, ZTC, Turbo 
and Borland Pascal. $89.95 PC Timer Objects 
provides similar services using C++ classes and 
Pascal Methods. Supports TC++, BC++, MSC++, 
ZTC++, Turbo/Borland Pascal Objects. $89.95 

All toolkits include full source & object code or 
driver distribution license, 30 day "No Questions 
Asked" return policy. VISA & MasterCard accepted. 
Add $5 shipping USA, $10 elsewhere. 

Ryle Design 

PO Box 22, Mt. Pleasant, Michigan 48804 USA 
Voice/Fax: 517.773.0587 
BBS: 517.772.2393 CIS: 73047,1765 
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Simtel20 MSDOS CDROM* $24.95 

640 megabytes in 9000+ files. Programming tools, DOS 
utilities, tech docs, comm, bbs, publishing, ham-radio, 
education, and much more. Dated September 1992. 


CICA MS Windows CDROM* $24.95 

Hundreds of MS Windows programs. Utilities, games, 
source code, and programming tools. Dated July 1992. 


Source Code CDROM* $39.95 

XIIR5 and GNU CDROM $39.95 

Info-Mac CDROM* $39.95 

OS/2 Archive CDROM* $24.95 

AB20 Amiga CDROM* $24.95 

Garbo MSDOS/MAC CDROM* $24.95 

CDROM Caddies $4.95 


*Shareware programs require separate payment 
to authors if found useful. 


Walnut Creek CDROM 



1547 Palos Verdes Mall 
Suite 260 
Walnut Creek, CA 94596 

+ 1-800-786-9907 

+1-510-947-5996 
FAX +1-510-947-1644 
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Discover why FoxPro, Clipper, 
and dBASE were all written in C. 


Mhere, is a good reason why 
* your database language was 
developed in C. In fact, there 
are many good reasons. 


C code is small. C code is fast. C code is 
portable. C code is flexible. C is the 
language of choice for today's professional 
developer. With the growing complexity of 
database applications, C is a realistic 
alternative. Now with CodeBase 5.0, you 
can have all the functionality, simplicity and 
power of traditional database languages 
together with the benefits of C/C++. 


C speed ■ fast code, true executables... 

FoxPro, Clipper, and dBASE were written 
in C primarily for speed. But those compilers 
don't really compile, they combine imbedded 
language interpreters into your .EXE. Now 
that's slow. For dazzling performance you 
need the true executables of C. With 
CodeBase you get the real thing, C code. 
Consider the following statistics, from the 
publisher of Clipper: 



slower 


FoxPro 
5 


"Sieve of Erastothenes" 

Benchmark for Prime Number Generation 
Shows C to be incredibly faster! 


C size - small executables, 
no added overhead... 

FoxPro, Clipper and dBASE would like you 
to believe you need their entire development 
system to build database applications. But 


remember, those products are all written in 
C. So why do you need to lug all their extra 
code around? You don't. CodeBase is a 
complete DBMS, in C. No fat executables 
stuffed with unused code. No runtime 
modules. No royalties. Just quality C code. 
CodeBase is just what you need. 


data files with any logical dBASE expression. 
Our new Bit Optimization Technology 
(similar to FoxPro's Rushmore technology) 
uses index files to return a query on a 1/2 
million record data file in just a second. 
Automatically take advantage of this query 
performance by using our new CodeReporter: 


C portability ■ ANSI C/C++ 
on every hardware platform... 

No other language exists on more platforms 
than C/C++. Why rewrite your entire 
application for DOS, Windows, Windows 
NT, OS/2 or UNIX? With CodeBase the 
complete C source code is included, so you 
can port to any platform with an ANSI C or 
C++ compiler. Now and in the future. 

dBASE Compatible data, index 
and memo files... 

You want the industry standard. You need 
compatibility. Sure, dBASE is the standard, 
but every dBASE compatible DBMS 
product uses its own unique index and memo 
file formats. Only CodeBase has them all: 
FoxPro (.cdx), Clipper (.ntx), dBASE IV 
(.mdx) and dBASE III (.ndx). Now it’s your 
choice, we're compatible with you. 

Announcing 
CodeBase 5l) 

The power of a complete DBMS, the benefits of C 

NEW - Multi-user sharing with 
FoxPro, Clipper and dBASE... 

Now your multi-user C/C++ programs can 
share data, index and memo files at the 
same time as concurrently running FoxPro, 
Clipper and dBASE programs. No 
incompatibilities. No waiting. 

NEW - Queries & Relations 
1000 times faster... 

CodeBase 5.0 now lets you query related 


Die Align Database Groups Global Print Query Styles Help 

Title: Objects: 1 Height: 36.0 Points 


Product Sales Sumri 

Product Sales 8ummary 

Month ol: Nov. 1992 

Product Quantity Value 

Database 63 *25.137.00 

Spread Sheer 59 *21.866 00 

Monthly Summary 121 $47,003.00 

Month: Header: Objects: 5: Height: 48.0 Points 

Month oh] IWTIUI 
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Body: Header: Ob|ecte. 3; Height: 14.0 Points 


Month: Footer: Objects: 4: Height: 48.0 Points 

Month oh Dad 992 

Product Ouantlty Value 

Database 62 *24.862 00 

Spread Shoot S3 *19.87500 

Monthly Summary 115 *44.737.00 

Summary; Objects: 3: Height: 36.0 Points 

gummd TOTAL 1 DOLLARI 




Summary 236 $91,740.00 

To use CodeReporter, 



simply draw your report, then include it in any 
program you write. Call 403/437-2410 now for 
your FREE working model of CodeReporter. 

New - Design complex reports 
in just minutes... 

Our new CodeReporter takes the painstaking 
work out of reports. Now simply design and 
draw reports interactively under Windows 3.1, 
then print or display them from any DOS, 
Windows or UNIX application. 

SPECIAL - FREE CodeReporter 

Order CodeBase 5 before June 30, 1993 
and receive CodeReporter for free! This 
offer includes our no-risk, 90-day money 
back guarantee, so order today! 



CodeBase 5.0 

The C/C++ Library for DataBase Management 

Call Now 
403 - 437-2410 


SEQUITER II FAX 403*436*2999 

SOFTWARE INC. Hill Eur °l* 33.20.24.20.14 


#209,9644-54 AVE., EDMONTON, AB, CANADA T6E-5V1 


61992 Sequitcr Software Inc. All rights reserved. CodeBase is a trademark of Sequiter Software Inc. All other trade names referenced herein are property of their respective companies. MAdvertising by MicroArts 
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ANOTHER DEBUGGING BREAKTHROUGH 



Automatic Bug Finder For Microsoft Windows 


NEW! BOUNDS-CHECKER for Windows is the only totally automatic 
solution to your Windows memory corruption, heap corruption and resource 
leakage problems. 

BOUNDS-CHECKER for Windows is an easy to use utility that automatically 
detects problems in your local heap, global heap, stack or data segment. It also 
tracks resource allocation / de-allocation, performs full parameter checking 
(even when not using the debug kernel) and handles all Windows faults. In one 
step, you can quickly and easily flush out some of the most aggravating bugs that 
a Windows programmer is likely to encounter. 

Using BOUNDS-CHECKER for Windows is simple, there are no changes 
to be made to your source in any way, and no linking of code or macros into 
your executable. When a bug is found, BOUNDS-CHECKER for Windows 
pops up shewing you the source code that caused the problem. 


BOUNDS-CHECKER for Windows 
quickly & easily traps: 

• Memory and heap related corruption problems 

• Library routine over-runs of strings, 
arrays and structures 

• Attempting to free bad blocks 

• NULL pointers the instant they are referenced 

• Resources that were not freed 

(shows your actual source line that created the resource) 

• Errant parameters passed to API routines 

• Processor Faults 

Order NOW! Only $199 


For even more debugging power at a great value you can order BOUNDS-CHECKER for Windows in one of our package 
bundles that include other Nu-Mega debugging tools: 

BOUNDS-CHECKER for DOS & BOUNDS-CHECKER for Windows $ 298 

BOUNDS-CHECKER & Soft-ICE (DOS or Windows versions) $499 

Get all 4 products (BOUNDS-CHECKER & Soft-ICE for DOS & Windows) $770 — SAVE $400! 


We're making C/C ++ a Safe Language! 


Call (603) 889-2386 
fax (603) 889-1135 

p Nu-Mega 

RISK = NULL 

30 DAY 

MONEY-BACK GUARANTEE 

P.O. Box 7780 

Nashua, NH 03060-7780 U.S.A. 

TECHNOLOGIES INC 

24 HOUR BBS 
603-595-0386 


BOUNDS-CHECKER FOR WINDOWS, SOFT-ICE, AND NU-MEGA TECHNOLOGIES are trademarks owned by Nu-Mega Technologies, Inc. All other trademarks are owned by their respective owners. 
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